kie-ai-mcp-server by andrewlwn77 - MCP Server

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 make
image_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 description
imageUrls (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-99999
watermark (string, optional): Watermark text
enableFallback (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 for
index (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_PATH to 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_KEY is 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

andrewlwn77/kie-ai-mcp-server

Kie.ai MCP Server

Features

Prerequisites

Installation

From NPM

From Source

Configuration

Environment Variables

MCP Configuration

Available Tools

1. generate_nano_banana

2. edit_nano_banana

3. generate_veo3_video

4. get_task_status

5. list_tasks

6. get_veo3_1080p_video

API Endpoints

Database Schema

Usage Examples

Basic Image Generation

Video Generation with Options

Error Handling

Development

Pricing

Production Tips

Troubleshooting

Common Issues

Support

License

Contributing

Changelog

v1.0.0

1. `generate_nano_banana`

2. `edit_nano_banana`

3. `generate_veo3_video`

4. `get_task_status`

5. `list_tasks`

6. `get_veo3_1080p_video`