{"_id":"@andrewlwn77/kie-ai-mcp-server","_rev":"3-d76dba3e08a1e15aafcb7ca144a53430","name":"@andrewlwn77/kie-ai-mcp-server","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@andrewlwn77/kie-ai-mcp-server","version":"1.0.0","keywords":["mcp","kie.ai","ai","image-generation","video-generation","nano-banana","veo3","model-context-protocol"],"author":{"name":"andrewlwn77"},"license":"MIT","_id":"@andrewlwn77/kie-ai-mcp-server@1.0.0","maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"homepage":"https://github.com/andrewlwn77/kie-ai-mcp-server#readme","bugs":{"url":"https://github.com/andrewlwn77/kie-ai-mcp-server/issues"},"dist":{"shasum":"3cd3a18309ae3da40edd52ac4da0f65a35f1bdc8","tarball":"https://registry.npmjs.org/@andrewlwn77/kie-ai-mcp-server/-/kie-ai-mcp-server-1.0.0.tgz","fileCount":17,"integrity":"sha512-OVbunDnJreSQy94Qm05bA1CjQz/697Sj/ObgWnqgA1kzRQsF+7bEzk6NKOM+h5RtLzqmVI9WGeONW54h1jCPBQ==","signatures":[{"sig":"MEUCIQDsQk1/Jijicrh4m0vjSbO6FAtBOwF4+PD+pGrBUKKQPgIgEWKUCrGvCD+S9S0HC5Z21c466JSgna6hlpvK0hEgeW4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62757},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"326f5364b09198d95bd25880a080169901d8705c","scripts":{"dev":"tsx src/index.ts","test":"jest","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"andrewlwn77","email":"andrewlwn@gmail.com"},"repository":{"url":"git+https://github.com/andrewlwn77/kie-ai-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Kie.ai APIs (Nano Banana image generation/editing and Veo3 video generation)","directories":{},"_nodeVersion":"22.13.1","dependencies":{"zod":"^3.22.4","sqlite3":"^5.1.6","@modelcontextprotocol/sdk":"^0.4.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.6.0","jest":"^29.7.0","typescript":"^5.3.0","@types/jest":"^29.5.8","@types/node":"^20.10.0","@types/sqlite3":"^3.1.11"},"_npmOperationalInternal":{"tmp":"tmp/kie-ai-mcp-server_1.0.0_1756778051322_0.6845757586349168","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@andrewlwn77/kie-ai-mcp-server","version":"1.0.1","keywords":["mcp","kie.ai","ai","image-generation","video-generation","nano-banana","veo3","model-context-protocol"],"author":{"name":"andrewlwn77"},"license":"MIT","_id":"@andrewlwn77/kie-ai-mcp-server@1.0.1","maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"homepage":"https://github.com/andrewlwn77/kie-ai-mcp-server#readme","bugs":{"url":"https://github.com/andrewlwn77/kie-ai-mcp-server/issues"},"bin":{"kie-ai-mcp-server":"dist/index.js"},"dist":{"shasum":"7b037a848913433d98664e77d4d864acc5c8ffe0","tarball":"https://registry.npmjs.org/@andrewlwn77/kie-ai-mcp-server/-/kie-ai-mcp-server-1.0.1.tgz","fileCount":17,"integrity":"sha512-DdFhnqmHdzQ1Mb1RhvArrcquyWl8DU4jty30J3fEVouXCADrtb47uAerrdD5qWVUefh25uaWZBFtbRuTU69tdg==","signatures":[{"sig":"MEQCIG1X40zWwlBOitBVPczITwPTIIldhF0/Ftm6w1js8NvDAiBSzcjoN6loJ2i4IW3Ykmkm5Vc4JSaCzy22COCdNOAWpg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62814},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"ce0fcc76462ecfb667cbf63fc47c127efbc8ad64","scripts":{"dev":"tsx src/index.ts","test":"jest","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"andrewlwn77","email":"andrewlwn@gmail.com"},"repository":{"url":"git+https://github.com/andrewlwn77/kie-ai-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Kie.ai APIs (Nano Banana image generation/editing and Veo3 video generation)","directories":{},"_nodeVersion":"22.13.1","dependencies":{"zod":"^3.22.4","sqlite3":"^5.1.6","@modelcontextprotocol/sdk":"^0.4.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.6.0","jest":"^29.7.0","typescript":"^5.3.0","@types/jest":"^29.5.8","@types/node":"^20.10.0","@types/sqlite3":"^3.1.11"},"_npmOperationalInternal":{"tmp":"tmp/kie-ai-mcp-server_1.0.1_1756778320400_0.8126054375169163","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@andrewlwn77/kie-ai-mcp-server","version":"1.0.2","description":"MCP server for Kie.ai APIs (Nano Banana image generation/editing and Veo3 video generation)","main":"dist/index.js","bin":{"kie-ai-mcp-server":"dist/index.js"},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts","test":"jest","prepublishOnly":"npm run build"},"keywords":["mcp","kie.ai","ai","image-generation","video-generation","nano-banana","veo3","model-context-protocol"],"author":{"name":"andrewlwn77"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/andrewlwn77/kie-ai-mcp-server.git"},"homepage":"https://github.com/andrewlwn77/kie-ai-mcp-server#readme","bugs":{"url":"https://github.com/andrewlwn77/kie-ai-mcp-server/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^0.4.0","sqlite3":"^5.1.6","zod":"^3.22.4"},"devDependencies":{"@types/node":"^20.10.0","@types/sqlite3":"^3.1.11","typescript":"^5.3.0","tsx":"^4.6.0","jest":"^29.7.0","@types/jest":"^29.5.8"},"engines":{"node":">=18.0.0"},"_id":"@andrewlwn77/kie-ai-mcp-server@1.0.2","gitHead":"40cc42eaee6a6c9b3a82ae7540d028f90009ab7b","types":"./dist/index.d.ts","_nodeVersion":"22.13.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-NWgBcR+t5BvIkQxQyvUJIqk8T4ciSsMygHEEMid851Mz7JaXIrTVePspuzrCE82zvji4ud3K3ZlTEBKLMHaDVg==","shasum":"a57a49a235fde24f73cf31a74986b33fa0257300","tarball":"https://registry.npmjs.org/@andrewlwn77/kie-ai-mcp-server/-/kie-ai-mcp-server-1.0.2.tgz","fileCount":17,"unpackedSize":63576,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDkdIPSbmirxUa0bgcPao8rBoqyB0E9mwSqt/cPEPjSKwIhALbZ19O6oH/A7ZgqqjvEeDua/v+1QtbFs93KbVjeNPGj"}]},"_npmUser":{"name":"andrewlwn77","email":"andrewlwn@gmail.com"},"directories":{},"maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kie-ai-mcp-server_1.0.2_1756830919400_0.11905224835712858"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-02T01:54:11.217Z","modified":"2025-09-02T16:35:19.780Z","1.0.0":"2025-09-02T01:54:11.555Z","1.0.1":"2025-09-02T01:58:40.594Z","1.0.2":"2025-09-02T16:35:19.616Z"},"bugs":{"url":"https://github.com/andrewlwn77/kie-ai-mcp-server/issues"},"author":{"name":"andrewlwn77"},"license":"MIT","homepage":"https://github.com/andrewlwn77/kie-ai-mcp-server#readme","keywords":["mcp","kie.ai","ai","image-generation","video-generation","nano-banana","veo3","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/andrewlwn77/kie-ai-mcp-server.git"},"description":"MCP server for Kie.ai APIs (Nano Banana image generation/editing and Veo3 video generation)","maintainers":[{"name":"andrewlwn77","email":"andrewlwn@gmail.com"}],"readme":"# Kie.ai MCP Server\n\nAn MCP (Model Context Protocol) server that provides access to Kie.ai's AI APIs including Nano Banana image generation/editing and Veo3 video generation.\n\n## Features\n\n- **Nano Banana Image Generation**: Text-to-image generation using Google's Gemini 2.5 Flash Image Preview\n- **Nano Banana Image Editing**: Natural language image editing with up to 5 input images\n- **Veo3 Video Generation**: Professional-quality video generation with text-to-video and image-to-video capabilities\n- **1080p Video Upgrade**: Get high-definition versions of Veo3 videos\n- **Task Management**: SQLite-based task tracking with status polling\n- **Smart Endpoint Routing**: Automatic detection of task types for status checking\n- **Error Handling**: Comprehensive error handling and validation\n\n## Prerequisites\n\n- Node.js 18+ \n- Kie.ai API key from https://kie.ai/api-key\n\n## Installation\n\n### From NPM\n\n```bash\nnpm install -g @andrewlwn77/kie-ai-mcp-server\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/andrewlwn77/kie-ai-mcp-server.git\ncd kie-ai-mcp-server\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Required\nexport KIE_AI_API_KEY=\"your-api-key-here\"\n\n# Optional\nexport KIE_AI_BASE_URL=\"https://api.kie.ai/api/v1\"  # Default\nexport KIE_AI_TIMEOUT=\"60000\"                      # Default: 60 seconds\nexport KIE_AI_DB_PATH=\"./tasks.db\"                 # Default: ./tasks.db\n```\n\n### MCP Configuration\n\nAdd to your Claude Desktop or MCP client configuration:\n\n```json\n{\n  \"kie-ai-mcp-server\": {\n    \"command\": \"node\",\n    \"args\": [\"/path/to/kie-ai-mcp-server/dist/index.js\"],\n    \"env\": {\n      \"KIE_AI_API_KEY\": \"your-api-key-here\"\n    }\n  }\n}\n```\n\nOr if installed globally:\n\n```json\n{\n  \"kie-ai-mcp-server\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"@andrewlwn77/kie-ai-mcp-server\"],\n    \"env\": {\n      \"KIE_AI_API_KEY\": \"your-api-key-here\"\n    }\n  }\n}\n```\n\n## Available Tools\n\n### 1. `generate_nano_banana`\nGenerate images using Nano Banana.\n\n**Parameters:**\n- `prompt` (string, required): Text description of the image to generate\n\n**Example:**\n```json\n{\n  \"prompt\": \"A surreal painting of a giant banana floating in space\"\n}\n```\n\n### 2. `edit_nano_banana`\nEdit images using natural language prompts.\n\n**Parameters:**\n- `prompt` (string, required): Description of edits to make\n- `image_urls` (array, required): URLs of images to edit (max 5)\n\n**Example:**\n```json\n{\n  \"prompt\": \"Add a rainbow arching over the mountains\",\n  \"image_urls\": [\"https://example.com/image.jpg\"]\n}\n```\n\n### 3. `generate_veo3_video`\nGenerate videos using Veo3.\n\n**Parameters:**\n- `prompt` (string, required): Video description\n- `imageUrls` (array, optional): Image for image-to-video (max 1)\n- `model` (enum, optional): \"veo3\" or \"veo3_fast\" (default: \"veo3\")\n- `aspectRatio` (enum, optional): \"16:9\" or \"9:16\" (default: \"16:9\")\n- `seeds` (integer, optional): Random seed 10000-99999\n- `watermark` (string, optional): Watermark text\n- `enableFallback` (boolean, optional): Enable fallback mechanism\n\n**Example:**\n```json\n{\n  \"prompt\": \"A dog playing in a park\",\n  \"model\": \"veo3\",\n  \"aspectRatio\": \"16:9\",\n  \"seeds\": 12345\n}\n```\n\n### 4. `get_task_status`\nCheck the status of a generation task.\n\n**Parameters:**\n- `task_id` (string, required): Task ID to check\n\n### 5. `list_tasks`\nList recent tasks with their status.\n\n**Parameters:**\n- `limit` (integer, optional): Max tasks to return (default: 20, max: 100)\n- `status` (string, optional): Filter by status (\"pending\", \"processing\", \"completed\", \"failed\")\n\n### 6. `get_veo3_1080p_video`\nGet 1080P high-definition version of a Veo3 video.\n\n**Parameters:**\n- `task_id` (string, required): Veo3 task ID to get 1080p video for\n- `index` (integer, optional): Video index (for multiple video results)\n\n**Note**: Not available for videos generated with fallback mode.\n\n## API Endpoints\n\nThe server interfaces with these Kie.ai API endpoints:\n\n- **Veo3 Video Generation**: `POST /api/v1/veo/generate` ✅ **VALIDATED**\n- **Veo3 Video Status**: `GET /api/v1/veo/record-info` ✅ **VALIDATED**  \n- **Veo3 1080p Upgrade**: `GET /api/v1/veo/get-1080p-video` ✅ **VALIDATED**\n- **Nano Banana Generation**: `POST /api/v1/playground/createTask` ✅ **VALIDATED**\n- **Nano Banana Status**: `GET /api/v1/playground/recordInfo` ✅ **VALIDATED**\n\nAll endpoints have been tested and validated with live API responses.\n\n## Database Schema\n\nThe server uses SQLite to track tasks:\n\n```sql\nCREATE TABLE tasks (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  task_id TEXT UNIQUE NOT NULL,\n  api_type TEXT NOT NULL,  -- 'nano-banana', 'nano-banana-edit', 'veo3'\n  status TEXT DEFAULT 'pending',\n  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n  result_url TEXT,\n  error_message TEXT\n);\n```\n\n## Usage Examples\n\n### Basic Image Generation\n```bash\n# Generate an image\ncurl -X POST http://localhost:3000/tools/call \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"generate_nano_banana\",\n    \"arguments\": {\n      \"prompt\": \"A cat wearing a space helmet\"\n    }\n  }'\n```\n\n### Video Generation with Options\n```bash\n# Generate a video\ncurl -X POST http://localhost:3000/tools/call \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"generate_veo3_video\",\n    \"arguments\": {\n      \"prompt\": \"A peaceful garden with blooming flowers\",\n      \"aspectRatio\": \"16:9\",\n      \"model\": \"veo3_fast\"\n    }\n  }'\n```\n\n## Error Handling\n\nThe server handles these HTTP error codes from Kie.ai:\n\n- **200**: Success\n- **400**: Content policy violation / English prompts only\n- **401**: Unauthorized (invalid API key)\n- **402**: Insufficient credits\n- **404**: Resource not found\n- **422**: Validation error / record is null\n- **429**: Rate limited\n- **451**: Image access limits\n- **455**: Service maintenance\n- **500**: Server error / timeout\n- **501**: Generation failed\n\n## Development\n\n```bash\n# Run tests\nnpm test\n\n# Development mode with auto-reload\nnpm run dev\n\n# Type checking\nnpx tsc --noEmit\n\n# Build for production\nnpm run build\n```\n\n## Pricing\n\nBased on Kie.ai documentation:\n- **Nano Banana**: $0.020 per image (4 credits)\n- **Veo3 Quality**: Higher cost tier\n- **Veo3 Fast**: ~20% of Quality model pricing\n\nSee https://kie.ai/billing for detailed pricing.\n\n## Production Tips\n\n1. **Database Location**: Set `KIE_AI_DB_PATH` to a persistent location\n2. **API Key Security**: Never commit API keys to version control\n3. **Rate Limiting**: Implement client-side rate limiting for high-volume usage\n4. **Monitoring**: Monitor task status and handle failed generations appropriately\n5. **Storage**: Consider automatic cleanup of old task records\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Unauthorized\" errors**\n- Verify `KIE_AI_API_KEY` is set correctly\n- Check API key is valid at https://kie.ai/api-key\n\n**\"Task not found\" errors**\n- Tasks may expire after 14 days\n- Check task ID format matches expected pattern\n\n**Generation failures**\n- Check content policy compliance\n- Verify prompt is in English\n- Ensure sufficient API credits\n\n## Support\n\nFor issues related to:\n- **MCP Server**: Open an issue at https://github.com/andrewlwn77/kie-ai-mcp-server/issues\n- **Kie.ai API**: Contact support@kie.ai or check https://docs.kie.ai/\n- **API Keys**: Visit https://kie.ai/api-key\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Changelog\n\n### v1.0.0\n- Initial release\n- Nano Banana image generation and editing\n- Veo3 video generation\n- 1080p video upgrade support\n- SQLite task tracking\n- Smart endpoint routing\n- Comprehensive error handling","readmeFilename":"README.md"}