Kie.ai MCP Server
An MCP (Model Context Protocol) server that provides access to Kie.ai's AI APIs including Nano Banana image generation/editing and Veo3 video generation.
Features
- Nano Banana Image Generation: Text-to-image generation using Google's Gemini 2.5 Flash Image Preview
- Nano Banana Image Editing: Natural language image editing with up to 5 input images
- Veo3 Video Generation: Professional-quality video generation with text-to-video and image-to-video capabilities
- 1080p Video Upgrade: Get high-definition versions of Veo3 videos
- Task Management: SQLite-based task tracking with status polling
- Smart Endpoint Routing: Automatic detection of task types for status checking
- Error Handling: Comprehensive error handling and validation
Prerequisites
- Node.js 18+
- Kie.ai API key from https://kie.ai/api-key
Installation
From NPM
npm install -g @andrewlwn77/kie-ai-mcp-server
From Source
# Clone the repository
git clone https://github.com/andrewlwn77/kie-ai-mcp-server.git
cd kie-ai-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
Configuration
Environment Variables
# Required
export KIE_AI_API_KEY="your-api-key-here"
# Optional
export KIE_AI_BASE_URL="https://api.kie.ai/api/v1" # Default
export KIE_AI_TIMEOUT="60000" # Default: 60 seconds
export KIE_AI_DB_PATH="./tasks.db" # Default: ./tasks.db
MCP Configuration
Add to your Claude Desktop or MCP client configuration:
{
"kie-ai-mcp-server": {
"command": "node",
"args": ["/path/to/kie-ai-mcp-server/dist/index.js"],
"env": {
"KIE_AI_API_KEY": "your-api-key-here"
}
}
}
Or if installed globally:
{
"kie-ai-mcp-server": {
"command": "npx",
"args": ["-y", "@andrewlwn77/kie-ai-mcp-server"],
"env": {
"KIE_AI_API_KEY": "your-api-key-here"
}
}
}
Available Tools
1. generate_nano_banana
Generate images using Nano Banana.
Parameters:
prompt(string, required): Text description of the image to generate
Example:
{
"prompt": "A surreal painting of a giant banana floating in space"
}
2. edit_nano_banana
Edit images using natural language prompts.
Parameters:
prompt(string, required): Description of edits to makeimage_urls(array, required): URLs of images to edit (max 5)
Example:
{
"prompt": "Add a rainbow arching over the mountains",
"image_urls": ["https://example.com/image.jpg"]
}
3. generate_veo3_video
Generate videos using Veo3.
Parameters:
prompt(string, required): Video descriptionimageUrls(array, optional): Image for image-to-video (max 1)model(enum, optional): "veo3" or "veo3_fast" (default: "veo3")aspectRatio(enum, optional): "16:9" or "9:16" (default: "16:9")seeds(integer, optional): Random seed 10000-99999watermark(string, optional): Watermark textenableFallback(boolean, optional): Enable fallback mechanism
Example:
{
"prompt": "A dog playing in a park",
"model": "veo3",
"aspectRatio": "16:9",
"seeds": 12345
}
4. get_task_status
Check the status of a generation task.
Parameters:
task_id(string, required): Task ID to check
5. list_tasks
List recent tasks with their status.
Parameters:
limit(integer, optional): Max tasks to return (default: 20, max: 100)status(string, optional): Filter by status ("pending", "processing", "completed", "failed")
6. get_veo3_1080p_video
Get 1080P high-definition version of a Veo3 video.
Parameters:
task_id(string, required): Veo3 task ID to get 1080p video forindex(integer, optional): Video index (for multiple video results)
Note: Not available for videos generated with fallback mode.
API Endpoints
The server interfaces with these Kie.ai API endpoints:
- Veo3 Video Generation:
POST /api/v1/veo/generate✅ VALIDATED - Veo3 Video Status:
GET /api/v1/veo/record-info✅ VALIDATED - Veo3 1080p Upgrade:
GET /api/v1/veo/get-1080p-video✅ VALIDATED - Nano Banana Generation:
POST /api/v1/playground/createTask✅ VALIDATED - Nano Banana Status:
GET /api/v1/playground/recordInfo✅ VALIDATED
All endpoints have been tested and validated with live API responses.
Database Schema
The server uses SQLite to track tasks:
CREATE TABLE tasks (
id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT UNIQUE NOT NULL,
api_type TEXT NOT NULL, -- 'nano-banana', 'nano-banana-edit', 'veo3'
status TEXT DEFAULT 'pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
result_url TEXT,
error_message TEXT
);
Usage Examples
Basic Image Generation
# Generate an image
curl -X POST http://localhost:3000/tools/call \
-H "Content-Type: application/json" \
-d '{
"name": "generate_nano_banana",
"arguments": {
"prompt": "A cat wearing a space helmet"
}
}'
Video Generation with Options
# Generate a video
curl -X POST http://localhost:3000/tools/call \
-H "Content-Type: application/json" \
-d '{
"name": "generate_veo3_video",
"arguments": {
"prompt": "A peaceful garden with blooming flowers",
"aspectRatio": "16:9",
"model": "veo3_fast"
}
}'
Error Handling
The server handles these HTTP error codes from Kie.ai:
- 200: Success
- 400: Content policy violation / English prompts only
- 401: Unauthorized (invalid API key)
- 402: Insufficient credits
- 404: Resource not found
- 422: Validation error / record is null
- 429: Rate limited
- 451: Image access limits
- 455: Service maintenance
- 500: Server error / timeout
- 501: Generation failed
Development
# Run tests
npm test
# Development mode with auto-reload
npm run dev
# Type checking
npx tsc --noEmit
# Build for production
npm run build
Pricing
Based on Kie.ai documentation:
- Nano Banana: $0.020 per image (4 credits)
- Veo3 Quality: Higher cost tier
- Veo3 Fast: ~20% of Quality model pricing
See https://kie.ai/billing for detailed pricing.
Production Tips
- Database Location: Set
KIE_AI_DB_PATHto a persistent location - API Key Security: Never commit API keys to version control
- Rate Limiting: Implement client-side rate limiting for high-volume usage
- Monitoring: Monitor task status and handle failed generations appropriately
- Storage: Consider automatic cleanup of old task records
Troubleshooting
Common Issues
"Unauthorized" errors
- Verify
KIE_AI_API_KEYis set correctly - Check API key is valid at https://kie.ai/api-key
"Task not found" errors
- Tasks may expire after 14 days
- Check task ID format matches expected pattern
Generation failures
- Check content policy compliance
- Verify prompt is in English
- Ensure sufficient API credits
Support
For issues related to:
- MCP Server: Open an issue at https://github.com/andrewlwn77/kie-ai-mcp-server/issues
- Kie.ai API: Contact support@kie.ai or check https://docs.kie.ai/
- API Keys: Visit https://kie.ai/api-key
License
MIT License - see LICENSE file for details.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
Changelog
v1.0.0
- Initial release
- Nano Banana image generation and editing
- Veo3 video generation
- 1080p video upgrade support
- SQLite task tracking
- Smart endpoint routing
- Comprehensive error handling