MCP Kling

Instructions

Implementation Reference

• src/kling-client.ts:334-374 (handler)

  Core handler function that validates input, processes image URLs, calls Kling AI /v1/videos/effects API, and returns task_id.

  async applyVideoEffect(request: VideoEffectsRequest): Promise<{ task_id: string }> {
    const path = '/v1/videos/effects';
    
    // Validate image count based on effect type
    const dualCharacterEffects = ['hug', 'kiss', 'heart_gesture'];
    const singleImageEffects = ['squish', 'expansion', 'fuzzyfuzzy', 'bloombloom', 'dizzydizzy'];
    
    if (dualCharacterEffects.includes(request.effect_scene) && request.image_urls.length !== 2) {
      throw new Error(`Effect "${request.effect_scene}" requires exactly 2 images`);
    }
    
    if (singleImageEffects.includes(request.effect_scene) && request.image_urls.length !== 1) {
      throw new Error(`Effect "${request.effect_scene}" requires exactly 1 image`);
    }
    
    // Process all image URLs
    const processedImageUrls = await Promise.all(
      request.image_urls.map(url => this.processImageUrl(url))
    );
    
    const body: any = {
      input: {
        image_urls: processedImageUrls.filter(url => url !== undefined),
        effect_scene: request.effect_scene,
        duration: request.duration || '5',
      }
    };
    
    // Always add model_name
    body.input.model_name = request.model_name || 'kling-v2-master';
  
    try {
      const response = await this.axiosInstance.post(path, body);
      return response.data.data;
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw new Error(`Kling API error: ${error.response?.data?.message || error.message}`);
      }
      throw error;
    }
  }

• src/kling-client.ts:73-78 (schema)

  TypeScript interface defining the input parameters for the applyVideoEffect function.

  export interface VideoEffectsRequest {
    image_urls: string[];
    effect_scene: 'hug' | 'kiss' | 'heart_gesture' | 'squish' | 'expansion' | 'fuzzyfuzzy' | 'bloombloom' | 'dizzydizzy';
    duration?: '5' | '10';
    model_name?: 'kling-v1' | 'kling-v1.5' | 'kling-v1.6' | 'kling-v2-master';
  }

• src/index.ts:296-325 (registration)

  MCP tool registration object defining name, description, and input schema for apply_video_effect.

  name: 'apply_video_effect',
  description: 'Apply pre-defined animation effects to static images using Kling AI. Create emotionally expressive videos from portraits with effects like hugging, kissing, or playful animations. Dual-character effects (hug, kiss, heart_gesture) require exactly 2 images. Single-image effects (squish, expansion, fuzzyfuzzy, bloombloom, dizzydizzy) require 1 image. Perfect for social media content and creative storytelling.',
  inputSchema: {
    type: 'object',
    properties: {
      image_urls: {
        type: 'array',
        items: {
          type: 'string',
        },
        description: 'Array of image URLs. Use 2 images for hug/kiss/heart_gesture effects, 1 image for squish/expansion/fuzzyfuzzy/bloombloom/dizzydizzy effects',
      },
      effect_scene: {
        type: 'string',
        enum: ['hug', 'kiss', 'heart_gesture', 'squish', 'expansion', 'fuzzyfuzzy', 'bloombloom', 'dizzydizzy'],
        description: 'The animation effect to apply. Dual-character: hug, kiss, heart_gesture. Single-image: squish, expansion, fuzzyfuzzy, bloombloom, dizzydizzy',
      },
      duration: {
        type: 'string',
        enum: ['5', '10'],
        description: 'Video duration in seconds (default: 5)',
      },
      model_name: {
        type: 'string',
        enum: ['kling-v1', 'kling-v1.5', 'kling-v1.6', 'kling-v2-master'],
        description: 'Model version to use (default: kling-v2-master)',
      },
    },
    required: ['image_urls', 'effect_scene'],
  },

• src/index.ts:606-624 (handler)

  MCP server request handler case that parses arguments, calls KlingClient.applyVideoEffect, and formats response.

  case 'apply_video_effect': {
    const effectRequest: VideoEffectsRequest = {
      image_urls: args.image_urls as string[],
      effect_scene: args.effect_scene as 'hug' | 'kiss' | 'heart_gesture' | 'squish' | 'expansion' | 'fuzzyfuzzy' | 'bloombloom' | 'dizzydizzy',
      duration: (args.duration as '5' | '10') || '5',
      model_name: (args.model_name as 'kling-v1' | 'kling-v1.5' | 'kling-v1.6' | 'kling-v2-master' | undefined) || 'kling-v2-master',
    };
  
    const result = await klingClient.applyVideoEffect(effectRequest);
    
    return {
      content: [
        {
          type: 'text',
          text: `Video effect "${effectRequest.effect_scene}" applied successfully!\nTask ID: ${result.task_id}\n\nThe effect video is being generated.\nUse the check_video_status tool with this task ID to check the progress.`,
        },
      ],
    };
  }