{"_id":"@snahrup/notion-hero-image-mcp","name":"@snahrup/notion-hero-image-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@snahrup/notion-hero-image-mcp","version":"1.0.0","description":"AI-powered animated hero banner generator for Notion pages. Integrates DALL-E 3, Google Veo 3, Cloudinary CDN, and Notion API.","type":"module","main":"dist/index.js","bin":{"notion-hero-mcp":"dist/index.js","notion-hero-mcp-setup":"setup-wizard.js"},"keywords":["mcp","notion","dalle","veo","ai","animation","hero-image","banner","cloudinary","model-context-protocol"],"author":{"name":"Steve Simkins"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/snahrup/notion-hero-image-mcp.git"},"bugs":{"url":"https://github.com/snahrup/notion-hero-image-mcp/issues"},"homepage":"https://github.com/snahrup/notion-hero-image-mcp#readme","scripts":{"build":"tsc","dev":"tsx src/index.ts","start":"node dist/index.js","test":"jest","setup":"node setup-wizard.js","postinstall":"node post-install.js"},"dependencies":{"@google-cloud/vertexai":"^1.9.2","@modelcontextprotocol/sdk":"^1.16.0","@notionhq/client":"^2.2.17","cloudinary":"^2.5.1","dotenv":"^17.2.0","fluent-ffmpeg":"^2.1.3","node-fetch":"^3.3.2","openai":"^4.77.3"},"devDependencies":{"@types/fluent-ffmpeg":"^2.1.27","@types/jest":"^29.5.14","@types/node":"^22.10.2","jest":"^29.7.0","ts-jest":"^29.2.5","tsx":"^4.19.2","typescript":"^5.7.2"},"_id":"@snahrup/notion-hero-image-mcp@1.0.0","gitHead":"0715001a00c8045a72f73686f3666049ff894b39","types":"./dist/index.d.ts","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-veZuSEWMigUgfFZkekwCTe3ZJQIdIpisIBN8qDHoLzM9gFGCd/A1SBPvHIxETrzUfpWLoxhZ1CDH7ql6hAj6rQ==","shasum":"baf77cce39bcd8fb0f814597cb1c9927349dbe32","tarball":"https://registry.npmjs.org/@snahrup/notion-hero-image-mcp/-/notion-hero-image-mcp-1.0.0.tgz","fileCount":40,"unpackedSize":88039,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFonBI0lbG8dAARlMIftVM+qOJZ2sog21Koxkkk2Mf3fAiBZC9vhX9HSiXUXK448p0CW5mvdBppYpv1DWHQyPTS6lg=="}]},"_npmUser":{"name":"snahrup","email":"snahrup@gmail.com"},"directories":{},"maintainers":[{"name":"snahrup","email":"snahrup@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/notion-hero-image-mcp_1.0.0_1753373480156_0.16321289357166302"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-24T16:11:20.047Z","1.0.0":"2025-07-24T16:11:20.383Z","modified":"2025-07-24T16:11:20.809Z"},"maintainers":[{"name":"snahrup","email":"snahrup@gmail.com"}],"description":"AI-powered animated hero banner generator for Notion pages. Integrates DALL-E 3, Google Veo 3, Cloudinary CDN, and Notion API.","homepage":"https://github.com/snahrup/notion-hero-image-mcp#readme","keywords":["mcp","notion","dalle","veo","ai","animation","hero-image","banner","cloudinary","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/snahrup/notion-hero-image-mcp.git"},"author":{"name":"Steve Simkins"},"bugs":{"url":"https://github.com/snahrup/notion-hero-image-mcp/issues"},"license":"MIT","readme":"# 🎨 Notion Hero Image MCP\n\nTransform your Notion pages with AI-powered animated hero banners! This MCP tool seamlessly integrates DALL-E 3, Google Veo 3, Cloudinary CDN, and the Notion API to create stunning animated covers for your Notion pages.\n\n## ✨ Features\n\n- **🖼️ AI Image Generation**: Create hero images using DALL-E 3 with custom prompts\n- **🎬 Video Animation**: Animate still images using Google Veo 3 with detailed animation scripts\n- **☁️ CDN Hosting**: Automatic upload to Cloudinary for fast, reliable hosting\n- **📄 Notion Integration**: Direct cover image updates for Notion pages\n- **🔄 Complete Pipeline**: End-to-end workflow from prompt to published banner\n- **🎯 Smart Conversion**: Automatic MP4 to GIF conversion with optimization\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 20.x or 22.x (Note: v24.3.0 has compatibility issues)\n- npm (comes with Node.js)\n\n### Installation\n\n```bash\n# Install globally (recommended)\nnpm install -g @snahrup/notion-hero-image-mcp\n\n# Run the interactive setup wizard\nnotion-hero-mcp-setup\n```\n\nThe setup wizard will guide you through:\n- 🔑 Getting API keys for each service\n- 🔧 Configuring your environment\n- 🤖 Setting up Claude Desktop automatically\n- ✅ Testing your installation\n\n### Alternative: Manual Installation\n\n```bash\n# Clone and install locally\ngit clone https://github.com/stevedsimkins/notion-hero-image-mcp.git\ncd notion-hero-image-mcp\nnpm install\n\n# Run setup wizard\nnpm run setup\n# or on Windows: setup.bat\n# or on Mac/Linux: ./setup.sh\n```\n## 🔧 Detailed Setup Guide\n\n### 1. OpenAI API Key\n\n1. Visit [OpenAI Platform](https://platform.openai.com/)\n2. Sign in or create an account\n3. Navigate to API Keys section\n4. Create a new API key\n5. Add to `.env`: `OPENAI_API_KEY=sk-proj-YOUR_KEY_HERE`\n\n### 2. Google Cloud Setup (for Veo 3)\n\n1. Create a Google Cloud Project:\n   ```bash\n   gcloud projects create YOUR_PROJECT_ID --name=\"Notion Hero MCP\"\n   ```\n\n2. Enable required APIs:\n   ```bash\n   gcloud services enable aiplatform.googleapis.com\n   ```\n\n3. Create a service account:\n   ```bash\n   gcloud iam service-accounts create notion-hero-mcp-sa \\\n     --display-name=\"Notion Hero MCP Service Account\"\n   ```\n\n4. Download the key file:\n   ```bash\n   gcloud iam service-accounts keys create notion-hero-image-mcp-sa-key.json \\\n     --iam-account=notion-hero-mcp-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com\n   ```\n5. Grant necessary permissions:\n   ```bash\n   gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \\\n     --member=\"serviceAccount:notion-hero-mcp-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com\" \\\n     --role=\"roles/aiplatform.user\"\n   ```\n\n6. Update `.env`:\n   ```\n   GOOGLE_PROJECT=YOUR_PROJECT_ID\n   GOOGLE_REGION=us-central1\n   GOOGLE_APPLICATION_CREDENTIALS=C:/path/to/notion-hero-image-mcp-sa-key.json\n   ```\n\n### 3. Cloudinary Setup\n\n1. Create a free account at [Cloudinary](https://cloudinary.com/)\n2. Navigate to Dashboard\n3. Copy your cloud name and API credentials\n4. Update `.env` with your credentials\n\n### 4. Notion Integration\n\n1. Visit [Notion Integrations](https://www.notion.so/my-integrations)\n2. Click \"New integration\"\n3. Name it \"Notion Hero Image MCP\"\n4. Select capabilities:\n   - Read content\n   - Update content\n   - Read comments (optional)\n5. Copy the Internal Integration Token\n6. Add to `.env`: `NOTION_API_TOKEN=ntn_YOUR_TOKEN_HERE`\n7. Share your Notion pages with the integration\n## 📋 Available Tools\n\n### 1. `generate_image`\nGenerate a hero still image using DALL-E 3.\n\n**Parameters:**\n- `prompt` (required): Visual description for the hero image\n- `style` (optional): Art style - \"cinematic\", \"illustration\", \"photorealistic\" (default: \"cinematic\")\n\n### 2. `generate_video`\nAnimate a still image using Google Veo 3.\n\n**Parameters:**\n- `image_url` (required): URL of the still image to animate\n- `title` (required): Title for the animation\n- `scene_description` (required): Detailed scene description\n- `style_tags` (optional): Style descriptors for the animation\n- `animation_beats` (optional): Timestamped animation sequences\n- `duration` (optional): Duration in seconds, max 8 (default: 8)\n\n### 3. `mp4_to_gif`\nConvert MP4 to optimized GIF under 10MB.\n\n**Parameters:**\n- `mp4_path` (required): Local path to MP4 file\n- `width` (optional): Output width (default: 640)\n- `fps` (optional): Frames per second (default: 15)\n\n### 4. `upload_to_cloudinary`\nUpload GIF to Cloudinary and return permanent URL.\n\n**Parameters:**\n- `gif_path` (required): Local path to GIF file\n- `folder` (optional): Cloudinary folder (default: \"notion-banners\")\n- `public_id` (optional): Public ID for the asset\n### 5. `set_notion_cover`\nSet a Notion page cover image from URL.\n\n**Parameters:**\n- `page_id` (required): Notion page ID (32 chars with hyphens)\n- `cover_url` (required): HTTPS URL of the cover image\n\n### 6. `create_notion_banner`\nComplete pipeline: Find Notion page by name, generate animated banner, and set as cover.\n\n**Parameters:**\n- `page_name` (required): Name of the Notion page\n- `prompt` (required): Creative prompt for the hero image\n- `style` (optional): Visual style (default: \"cinematic\")\n- `references` (optional): URLs or descriptions of reference images\n- `custom_animation` (optional): Custom animation configuration\n\n### 7. `preview_banner_creation`\nPreview the banner creation plan before executing.\n\n**Parameters:**\n- `page_name` (required): Name of the Notion page\n- `user_request` (required): Natural language request for the banner\n- `style_preference` (optional): Preferred visual style\n\n## 🎯 Usage Examples\n\n### Basic Usage\n```typescript\n// Generate a simple animated banner\nawait create_notion_banner({\n  page_name: \"My Project\",\n  prompt: \"A futuristic cityscape with flying cars at sunset\"\n});\n```\n### Advanced Usage with Custom Animation\n```typescript\nawait create_notion_banner({\n  page_name: \"AI Research\",\n  prompt: \"Neural networks visualized as glowing interconnected nodes\",\n  style: \"cyberpunk\",\n  custom_animation: {\n    title: \"Neural Network Awakening\",\n    scene_description: \"A dark void where neural pathways begin to illuminate\",\n    style_tags: \"cinematic, sci-fi, dramatic lighting\",\n    animation_beats: [\n      {\n        timeRange: \"0s-2s\",\n        description: \"Darkness, then a single node sparks to life\"\n      },\n      {\n        timeRange: \"2s-5s\",\n        description: \"Energy cascades through connections exponentially\"\n      },\n      {\n        timeRange: \"5s-8s\",\n        description: \"Full network pulses with synchronized data flow\"\n      }\n    ]\n  }\n});\n```\n\n### Manual Pipeline\n```typescript\n// Step 1: Generate image\nconst image = await generate_image({\n  prompt: \"Serene mountain landscape at golden hour\"\n});\n\n// Step 2: Animate it\nconst video = await generate_video({\n  image_url: image.url,\n  title: \"Mountain Majesty\",\n  scene_description: \"Clouds drift across peaks as light shifts\"\n});\n\n// Step 3: Convert to GIF\nconst gif = await mp4_to_gif({\n  mp4_path: video.local_path\n});\n\n// Step 4: Upload to CDN\nconst hosted = await upload_to_cloudinary({\n  gif_path: gif.path\n});\n\n// Step 5: Set as Notion cover\nawait set_notion_cover({\n  page_id: \"your-page-id-here\",\n  cover_url: hosted.url\n});\n```\n## 🏗️ Architecture\n\n```\nUser Request\n     │\n     ▼\n┌─────────────┐\n│   DALL-E 3  │ ─── Generate hero still image\n└─────────────┘\n     │\n     ▼\n┌─────────────┐\n│ Google Veo 3│ ─── Animate with custom script\n└─────────────┘\n     │\n     ▼\n┌─────────────┐\n│  FFmpeg     │ ─── Convert MP4 to optimized GIF\n└─────────────┘\n     │\n     ▼\n┌─────────────┐\n│ Cloudinary  │ ─── Host on global CDN\n└─────────────┘\n     │\n     ▼\n┌─────────────┐\n│ Notion API  │ ─── Update page cover\n└─────────────┘\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **\"Failed to find ffmpeg\"**\n   - Install FFmpeg: Download from [ffmpeg.org](https://ffmpeg.org/)\n   - Add to PATH or set FFMPEG_PATH environment variable\n\n2. **\"Google Cloud authentication failed\"**\n   - Ensure service account key file exists at specified path\n   - Verify the service account has necessary permissions\n   - Check GOOGLE_APPLICATION_CREDENTIALS path uses forward slashes or escaped backslashes\n3. **\"Notion page not found\"**\n   - Share the page with your integration\n   - Ensure page name matches exactly (case-sensitive)\n   - Try using page ID instead of name\n\n4. **\"GIF exceeds 10MB limit\"**\n   - Reduce width parameter (try 480 or 320)\n   - Lower fps (try 10 or 12)\n   - Shorten animation duration\n\n### Debug Mode\n\nEnable verbose logging by setting:\n```bash\nexport DEBUG=notion-hero-mcp:*\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- OpenAI for DALL-E 3 API\n- Google Cloud for Veo 3 video generation\n- Cloudinary for reliable CDN hosting\n- Notion for their excellent API\n- The MCP ecosystem for enabling seamless tool integration\n\n## 📧 Support\n\nFor issues, questions, or suggestions:\n- Open an issue on GitHub\n- Contact: your-email@example.com\n\n---\n\nMade with ❤️ for the Notion community","readmeFilename":"README.md","_rev":"1-7d96fd05e4101efc6cc7ceefae94b2b7"}