Skip to content

andrewlwn77/kie-ai-mcp-server

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5 Commits
src
src
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

Repository files navigation

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

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

  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

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:

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

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

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

5 stars

Watchers

0 watching

Forks

5 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages