Skip to content

felores/kie-ai-mcp-server

BranchesTags
 
 

Repository files navigation

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

🚀 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.

🎛️ Filter Tools (optional - click to expand)

Reduce cognitive load by enabling only the tools you need:

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": "nano_banana_image,veo3_generate_video,suno_generate_music"
      }
    }
  }
}

Category filter (enable by type):

{
  "mcpServers": {
    "kie-ai": {
      "command": "npx",
      "args": ["-y", "@felores/kie-ai-mcp-server"],
      "env": {
        "KIE_AI_API_KEY": "your-api-key-here",
        "KIE_AI_TOOL_CATEGORIES": "image,video"
      }
    }
  }
}

Blacklist (disable specific tools):

{
  "mcpServers": {
    "kie-ai": {
      "command": "npx",
      "args": ["-y", "@felores/kie-ai-mcp-server"],
      "env": {
        "KIE_AI_API_KEY": "your-api-key-here",
        "KIE_AI_DISABLED_TOOLS": "midjourney_generate,runway_aleph_video"
      }
    }
  }
}

Categories: image | video | audio — Utility tools (list_tasks, get_task_status) are always enabled.

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
  • OpenAI Sora 2: Advanced video generation with text/image/storyboard modes (unified)
  • 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)
  • OpenAI 4o Image: Advanced image generation, editing, and variant creation with GPT-4o (unified)
  • Flux Kontext: Professional image generation and editing with advanced features (unified)
  • Alibaba Wan 2.5: High-quality video generation with text-to-video and image-to-video (unified)
  • 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 workflow
  • kie://agents/filmographer - Complete video generation workflow

Model Documentation (33+ models):

  • kie://models/bytedance-seedream - 4K image generation
  • kie://models/veo3 - Premium cinematic video
  • kie://models/qwen-image - Fast image processing
  • kie://models/flux-kontext - Professional image generation
  • ...and 29 more models

Comparison Guides:

  • kie://guides/image-models-comparison - Feature matrix for all image models
  • kie://guides/video-models-comparison - Feature matrix for all video models
  • kie://guides/quality-optimization - Cost/quality strategies

🛠️ 21 Unified AI Tools

All tools feature smart mode detection - one tool does multiple things:

Category Tools
Image (7) bytedance_seedream_image, qwen_image, nano_banana_image, flux_kontext_image, openai_4o_image, recraft_remove_background, ideogram_reframe
Video (8) veo3_generate_video, sora_video, bytedance_seedance_video, wan_video, hailuo_video, kling_video, runway_aleph_video, midjourney_generate
Audio (3) suno_generate_music, elevenlabs_tts, elevenlabs_ttsfx
Utility (3) list_tasks, get_task_status, veo3_get_1080p_video

→ 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 (8): nano_banana, seedream, qwen, openai_4o, flux, recraft, ideogram, midjourney*
  • video (9): veo3, veo3_1080p, sora, seedance, wan, hailuo, kling, runway, 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": "sora_video",
  "arguments": {
    "prompt": "A peaceful garden with blooming flowers and butterflies",
    "model": "sora-2",
    "resolution": "1080p",
    "duration": "10"
  }
}

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
sora_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
openai_4o_image: "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

  1. Database Location: Set KIE_AI_DB_PATH to a persistent location
  2. API Key Security: Never commit API keys to version control
  3. Rate Limiting: Implement client-side rate limiting for high-volume usage
  4. Monitoring: Monitor task status and handle failed generations appropriately
  5. Storage: Consider automatic cleanup of old task records

→ See complete administrator guide for deployment best practices

Troubleshooting

Common Issues

"Unauthorized" errors

"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:

🚀 Start Building with Kie.ai

🎯 Get Started

  1. Get your free API key at kie.ai/api-key
  2. Install the MCP server: npm install @felores/kie-ai-mcp-server
  3. 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

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Changelog

See CHANGELOG.md for detailed version history and release notes.

About

Kie.ai MCP Server: The most cost efficient media API in the market ready to be used by your MCP client as a smart MCP Server with intent detection. Generative Ai Models available: Nano Banana Pro, Veo3 , Runway Aleph, Suno V5, ElevenLabs, Seedance, Seedream, Qwen, Flux Kontext, Wan and Midjourney

www.npmjs.com/package/@felores/kie-ai-mcp-server

Topics

typescript ai mcp image-generation video-generation model-context-protocol veo3 nano-banana kie-ai

Resources

Readme

License

MIT license
Activity

Stars

15 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases 31

Release v3.1.0 Latest
Apr 16, 2026
+ 30 releases

Packages

 
 
 

Contributors

Languages

  • JavaScript 73.0%
  • TypeScript 27.0%