Kie AI MCP Server
MCP server for Kie.ai APIs (24 AI tools: Nano Banana image generation/editing/upscaling, Veo3 video generation, Suno music generation, ElevenLabs TTS/sound effects, ByteDance Seedance/Seedream video/image, Qwen image generation/editing, Runway Aleph video
Ask AI about Kie AI MCP Server
Powered by Claude ยท Grounded in docs
I know everything about Kie AI MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Kie.ai MCP Server
Access State of the Art AI models at half the price using one MCP Server. Generate videos, images, music, and audio with the latest generative AI technologies using a developer-friendly API.
Kie.ai offers 30-50% lower cost than competitors with 99.9% uptime and 24/7 human support.
๐ Documentation
- Complete Tool Reference - Detailed documentation for all 24 AI tools
- Database & Task Management - SQLite database and task lifecycle
- Administrator Configuration - Deployment guides and environment setup
- Intelligent Features - Smart mode detection and cost optimization
๐ Quick Start - Add to Your MCP Client
The easiest way to use this server is to add it to your MCP client configuration:
{
"mcpServers": {
"kie-ai": {
"command": "npx",
"args": ["-y", "@felores/kie-ai-mcp-server"],
"env": {
"KIE_AI_API_KEY": "your-api-key-here"
}
}
}
}
Get your free API key: kie.ai/api-key
That's it! No callback URL setup required - the server handles it automatically.
๐๏ธ Enable Only the Tools You Need
25 tools is a lot. Reduce cognitive load by enabling only what you use. Add the env var to the config above:
Whitelist (enable specific tools only):
{
"mcpServers": {
"kie-ai": {
"command": "npx",
"args": ["-y", "@felores/kie-ai-mcp-server"],
"env": {
"KIE_AI_API_KEY": "your-api-key-here",
"KIE_AI_ENABLED_TOOLS": "gpt_image_2,wan_video,suno_generate_music"
}
}
}
}
Category filter (enable all image + video tools):
"KIE_AI_TOOL_CATEGORIES": "image,video"
Blacklist (disable specific tools):
"KIE_AI_DISABLED_TOOLS": "midjourney_generate,runway_aleph_video"
Categories: image (9) | video (11) | audio (3) -- Utility tools (list_tasks, get_task_status) are always enabled.
Priority: ENABLED_TOOLS > TOOL_CATEGORIES > DISABLED_TOOLS > all tools (default)
For Claude Desktop: Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
Works with Cursor, Windsurf, VS Code, Claude Code, OpenCode, Droid, etc.
Why Choose Kie.ai MCP Server?
| Feature | Kie.ai | Fal.ai | Replicate.com |
|---|---|---|---|
| Pricing | 30-50% Lower | Higher | Higher |
| Uptime | 99.9% | Not disclosed | Not disclosed |
| Support | 24/7 Human | Email + Discord | 24/7 AI |
| Free Trial | Yes | Limited | Limited |
๐ All AI Models in One API
- Google Veo 3: Cinematic video generation with synchronized audio and 1080p output
- Runway Aleph: Advanced video editing with object removal and style transfer
- Suno V5: Professional music generation with realistic vocals up to 8 minutes
- Nano Banana 2: Lightning-fast image generation and editing with Google Search grounding (unified tool)
- ElevenLabs: Studio-quality text-to-speech and sound effects
- ByteDance Seedance: High-quality video with text-to-video and image-to-video (unified)
- ByteDance Seedream V5 Lite: Advanced image generation and editing with unified interface
- Qwen: Powerful image generation and editing with acceleration options (unified)
- GPT Image 2: Advanced image generation and editing with up to 16 reference images (unified)
- Flux Kontext: Professional image generation and editing with advanced features (unified)
- Alibaba Wan 2.7: Multi-mode video generation with T2V, I2V, R2V, and video-edit (unified)
- HappyHorse 1.0: Multi-mode video generation with T2V, I2V, R2V (9 refs), and video-edit with audio
- Hailuo 02: Professional video generation with text-to-video and image-to-video modes (unified, standard/pro quality)
- Kling 3.0: Advanced video generation with 3-15s duration, multi-shot storytelling, and native audio
- Midjourney AI: Industry-leading image and video generation with multiple modes (unified)
- Recraft Remove Background: Professional AI-powered background removal
- Ideogram V3 Reframe: Intelligent image reframing and aspect ratio conversion
What You Can Build
| Category | Use Cases |
|---|---|
| ๐ฌ Video Generation | Social media content, marketing materials, product demonstrations, creative projects |
| ๐จ Image Generation | Content creation, product photography, artistic projects, design mockups |
| ๐ต Music Generation | Background music for videos, podcast intros/outros, game soundtracks, commercial projects |
| ๐ค Audio Generation | Narration and voiceovers, podcast production, game audio, accessibility features |
MCP Features
๐จ Agent Prompts (Slash Commands)
Trigger specialized AI agents with simple commands in your MCP client:
-
/artist- Image generation and editing agent
Just describe what you want: "/artist create a logo for a coffee shop" -
/filmographer- Video generation agent
Just describe what you want: "/filmographer create a 10-second sunset video"
๐ Knowledge Resources
Your AI assistant can research and learn about available models before using them:
Agent Instructions:
kie://agents/artist- Complete image generation workflowkie://agents/filmographer- Complete video generation workflow
Model Documentation (33+ models):
kie://models/bytedance-seedream- 4K image generationkie://models/veo3- Premium cinematic videokie://models/qwen-image- Fast image processingkie://models/flux-kontext- Professional image generation- ...and 29 more models
Comparison Guides:
kie://guides/image-models-comparison- Feature matrix for all image modelskie://guides/video-models-comparison- Feature matrix for all video modelskie://guides/quality-optimization- Cost/quality strategies
๐ ๏ธ 24 Unified AI Tools
All tools feature smart mode detection - one tool does multiple things:
| Category | Tools |
|---|---|
| Image (9) | nano_banana_image, bytedance_seedream_image, qwen_image, gpt_image_2, flux_kontext_image, flux2_image, topaz_upscale_image, recraft_remove_background, ideogram_reframe |
| Video (10) | veo3_generate_video, bytedance_seedance_video, wan_video, happyhorse_video, hailuo_video, kling_video, runway_aleph_video, wan_animate, midjourney_generate |
| Audio (3) | suno_generate_music, elevenlabs_tts, elevenlabs_ttsfx |
| Utility (2) | list_tasks, get_task_status |
โ See complete tool documentation
Key Features
- ๐ฏ One API Key: Access all models with one credential
- ๐ค AI Agent Prompts: Slash commands trigger specialized workflows
- ๐ Knowledge Base: 33+ resources for model research and comparison
- ๐ Task Management: Built-in SQLite database for tracking generations
- ๐ฑ Smart Routing: Automatic endpoint detection and status monitoring
- ๐ก๏ธ Error Handling: Validation and error recovery
- โ๏ธ Flexible Parameters: Control outputs with parameters
- ๐ Persistent Storage: Tasks survive server restarts
- ๐๏ธ Quality Control: Choose between speed (lite) and quality (pro) modes
- ๐ Multilingual Support: Text-to-speech in multiple languages
๐ง Intelligent Intention Detection System
The MCP server features advanced intention detection algorithms that automatically understand user requirements and optimize both cost and quality without manual configuration.
Quick Summary
- Automatic Quality Detection: Analyzes user language ("high quality" โ pro models, "quick" โ lite models)
- Smart Mode Detection: Single tools auto-detect operation mode (generate/edit/upscale) based on parameters
- Database-Driven Intelligence: Local SQLite cache reduces API calls and provides smart routing
- Cost Control by Design: Defaults to cheapest options (720p, lite quality) unless explicitly requested
Example: User says "Make a quick social media video" โ System automatically chooses: lite quality + 720p + 5 second duration = lowest cost tier (1x baseline)
Example: User says "I need a high quality video for a client presentation" โ System automatically chooses: pro quality + 1080p = highest cost tier (4-6x baseline)
โ See complete intelligence documentation with real-world examples and verifiable code references
Installation & Configuration
๐ฆ Installation Options (click to expand)
Option 1: Install from NPM (Recommended)
npm install -g @felores/kie-ai-mcp-server
Option 2: Install from Source
# Clone the repository
git clone https://github.com/felores/kie-ai-mcp-server.git
cd kie-ai-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
โ๏ธ Environment Variables (click to expand)
Required
export KIE_AI_API_KEY="your-api-key-here" # Get from https://kie.ai/api-key
Optional
export KIE_AI_BASE_URL="https://api.kie.ai/api/v1" # Default API base URL
export KIE_AI_TIMEOUT="60000" # Request timeout (ms)
export KIE_AI_DB_PATH="./tasks.db" # Database file location
export KIE_AI_CALLBACK_URL="https://your-domain.com/webhook" # Custom callback
export KIE_AI_CALLBACK_URL_FALLBACK="https://your-proxy.com/callback" # Admin fallback
Callback URL Priority
| Priority | Source | Variable | Use Case |
|---|---|---|---|
| 1 | User Parameter | callBackUrl | Per-request override |
| 2 | Environment | KIE_AI_CALLBACK_URL | User's custom callback |
| 3 | Admin Fallback | KIE_AI_CALLBACK_URL_FALLBACK | โญ Deployment-wide default |
| 4 | Hardcoded | - | https://proxy.kie.ai/mcp-callback |
โ See administrator configuration guide for Docker, Kubernetes, Systemd examples
Tool Filtering (v2.0.2+)
Filter which AI tools are available to reduce cognitive load and focus your workflow:
# Whitelist: Enable only specific tools (highest priority)
# Note: Utility tools (list_tasks, get_task_status) are always included automatically
export KIE_AI_ENABLED_TOOLS="nano_banana_image,veo3_generate_video,suno_generate_music"
# Category filter: Enable by category (medium priority)
export KIE_AI_TOOL_CATEGORIES="image,video" # Categories: image, video, audio
# Blacklist: Disable specific tools (lowest priority)
# Note: Utility tools cannot be disabled
export KIE_AI_DISABLED_TOOLS="midjourney_generate,runway_aleph_video"
Priority Logic: ENABLED_TOOLS > TOOL_CATEGORIES > DISABLED_TOOLS > All tools (default)
Tool Categories:
- image (9): nano_banana, seedream, qwen, gpt_image_2, flux_kontext, flux2, topaz, recraft, ideogram, midjourney*
- video (10): veo3, seedance, wan_video, happyhorse_video, hailuo, kling, runway, wan_animate, midjourney*
- audio (3): suno, elevenlabs_tts, elevenlabs_ttsfx
- utility (2): list_tasks, get_task_status โญ Always enabled
* midjourney appears in both image and video categories (supports both)
- โญ Utility tools are always enabled for server monitoring and task management
- When using whitelist mode, utility tools are automatically added to your selection
- When using blacklist mode, utility tools cannot be disabled (warning shown if attempted)
๐ง MCP Client Configuration (click to expand)
Claude Desktop, Cursor, Windsurf, VS Code, etc.
Add to your MCP client configuration file:
{
"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 with npx:
{
"kie-ai-mcp-server": {
"command": "npx",
"args": ["-y", "@felores/kie-ai-mcp-server"],
"env": {
"KIE_AI_API_KEY": "your-api-key-here"
}
}
}
Quick Examples
Generate Image
{
"tool": "nano_banana_image",
"arguments": {
"prompt": "A futuristic city at sunset, cyberpunk style",
"image_size": "16:9",
"output_format": "png"
}
}
Generate Video
{
"tool": "wan_video",
"arguments": {
"prompt": "A peaceful garden with blooming flowers and butterflies",
"resolution": "1080p",
"duration": 5
}
}
Generate Music
{
"tool": "suno_generate_music",
"arguments": {
"prompt": "Upbeat electronic music with energetic beats",
"customMode": true,
"instrumental": false,
"model": "V5",
"style": "Electronic",
"title": "Energy Boost"
}
}
Text-to-Speech
{
"tool": "elevenlabs_tts",
"arguments": {
"text": "Welcome to the future of AI-powered content creation!",
"voice": "Rachel",
"model": "turbo"
}
}
โ See 100+ more examples in tool documentation
Database & Task Management
The server includes a built-in SQLite database for persistent task tracking:
- ๐ Persistent Storage: Tasks survive server restarts
- ๐ Complete History: Track all generation tasks and their results
- โก Smart Caching: Local database reduces API calls
- ๐ Full Audit Trail: Complete lifecycle tracking
- ๐ฏ Intelligent Routing: Database provides api_type for correct endpoint selection
Quick Examples
List recent tasks:
{
"tool": "list_tasks",
"arguments": {
"limit": 20,
"status": "completed"
}
}
Check task status:
{
"tool": "get_task_status",
"arguments": {
"task_id": "281e5b0*********************f39b9"
}
}
โ See complete database documentation including schema, lifecycle, and best practices
Real-World Use Cases
๐ฌ Content Creation Agencies (click to expand)
# Generate social media video content
wan_video: "A trendy coffee shop with latte art, cinematic lighting"
# Create product photography
nano_banana_image: "Luxury watch on marble surface, professional product shot"
# Add background music
suno_generate_music: "Upbeat corporate background music, 2 minutes"
๐ฎ Game Development Studios (click to expand)
# Generate game assets
bytedance_seedream_image: "Fantasy sword with glowing runes, game asset style"
# Create character voiceovers
elevenlabs_tts: "Welcome, brave adventurer! Your quest begins now."
# Design sound effects
elevenlabs_ttsfx: "Magical spell casting with sparkles and energy"
๐ฑ Mobile App Developers (click to expand)
# Generate app icons and illustrations
flux_kontext_image: "Modern minimalist app icon for fitness tracker"
# Create tutorial videos
bytedance_seedance_video: "Screen recording showing app features, clean interface"
# Add narration
elevenlabs_tts: "Tap here to get started with your new profile"
๐ข Enterprise Applications (click to expand)
# Generate training materials
veo3_generate_video: "Professional office environment, employee training scenario"
# Create corporate presentations
gpt_image_2: "Add company logo to presentation slide, maintain professional style"
# Produce marketing content
suno_generate_music: "Corporate background music for promotional video"
Error Handling
The server handles these HTTP error codes from Kie.ai:
| Code | Meaning |
|---|---|
| 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
โ See complete administrator guide for deployment best practices
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/felores/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
๐ Start Building with Kie.ai
๐ฏ Get Started
- Get your free API key at kie.ai/api-key
- Install the MCP server:
npm install @felores/kie-ai-mcp-server - Generate your first AI content in minutes
๐ก Benefits
- โ Free trial - Test models before paying
- โ 30-50% lower pricing than competitors
- โ 99.9% uptime guarantee
- โ 24/7 human support
- โ Simple integration
๐ AI Content Generation
Kie.ai provides access to advanced AI models at competitive pricing.
Start your project today. ๐
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
See CHANGELOG.md for detailed version history and release notes.
