mcp-video-analyser

A stdio-based MCP (Model Context Protocol) server for video analysis using Google Gemini and Moonshot Kimi AI.

Features

• Analyze video files with AI vision models
• Support for multiple providers: Google Gemini and Moonshot Kimi
• Interactive setup wizard for easy configuration
• User-scope or project-scope configuration
• Environment variable support with fallback defaults
• Video file validation (format, size, magic bytes)
• TypeScript with strict type checking

Installation

npm install -g mcp-video-analyser
# or
bun install -g mcp-video-analyser

Quick Start

1. Run Setup

mcp-video-analyser setup

This will guide you through configuring your providers and API keys.

2. Configure Your MCP Client

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "mcp-video-analyser": {
      "command": "mcp-video-analyser",
      "env": {
        "GOOGLE_API_KEY": "your-google-api-key",
        "MOONSHOT_API_KEY": "your-moonshot-api-key"
      }
    }
  }
}

3. Use the Tools

The server provides these MCP tools:

• analyze_video - Analyze a local video file with an AI prompt
• list_providers - List available providers and their models
• get_config - View current configuration (API keys masked)

Configuration

Config File Locations

| Scope | Path | |-------|------| | User (default) | ~/.config/mcp-video-analyser/config.jsonc | | Project | ./.config/mcp-video-analyser/config.jsonc |

Config Schema

{
  // Default provider: google or kimi
  "defaultProvider": "google",
  
  // Default model when not specified
  "defaultModel": "gemini-2.5-flash",
  
  // Provider configurations
  "providers": {
    "google": {
      // Supports: plain text, $ENV_VAR, ${ENV_VAR}, ${ENV_VAR:fallback}
      "apiKey": "${GOOGLE_API_KEY}",
      "enabled": true
    },
    "kimi": {
      "apiKey": "${MOONSHOT_API_KEY}",
      "baseUrl": "https://api.moonshot.ai/v1",
      "enabled": false
    }
  },
  
  // Video validation settings
  "video": {
    "maxSizeMB": 100,
    "supportedFormats": ["mp4", "webm", "mov", "avi", "mkv"]
  },
  
  // Analysis defaults
  "analysis": {
    "temperature": 0.6,
    "maxTokens": 8192
  }
}

Environment Variable Syntax

API keys in config support these formats:

"sk-your-plain-api-key"        # Plain text
"$GOOGLE_API_KEY"              # Direct env reference
"${GOOGLE_API_KEY}"            # Curly brace syntax
"${GOOGLE_API_KEY:fallback}"   # With fallback default

CLI Commands

# Interactive setup wizard
mcp-video-analyser setup

# Setup with explicit scope
mcp-video-analyser setup --scope user
mcp-video-analyser setup --scope project

# Start MCP server (default command)
mcp-video-analyser
mcp-video-analyser serve

# Show version
mcp-video-analyser --version

# Show help
mcp-video-analyser --help

Supported Providers

Google Gemini

| Model | Description | |-------|-------------| | gemini-2.5-flash | Recommended - fast & capable | | gemini-2.5-pro | Most powerful | | gemini-2.0-flash | Previous generation | | gemini-1.5-pro | Up to 1hr video | | gemini-1.5-flash | Budget-friendly |

Requirements:

• Google AI API key from Google AI Studio
• Videos are uploaded via Google's File API for processing

Moonshot Kimi

| Model | Description | |-------|-------------| | kimi-k2.5 | Latest - multimodal agent | | kimi-k2 | Previous generation |

Requirements:

• Moonshot API key from Moonshot AI
• Videos are sent as base64-encoded data

Supported Video Formats

• MP4 (.mp4)
• WebM (.webm)
• QuickTime (.mov)
• AVI (.avi)
• Matroska (.mkv)

Maximum file size: 100 MB (configurable)

Development

Prerequisites

• Node.js >= 20.0.0
• Bun (recommended) or npm

Setup

# Clone the repository
git clone https://github.com/your-repo/mcp-video-analyser.git
cd mcp-video-analyser

# Install dependencies
bun install

# Build
bun run build

# Run in development
bun run dev

Scripts

| Script | Description | |--------|-------------| | bun run build | Compile TypeScript | | bun run dev | Run server in development | | bun run dev:cli | Run CLI in development | | bun run setup | Run setup wizard | | bun run lint | Run linting | | bun run format | Format code | | bun run check | Run all checks |

Project Structure

mcp-video-analyser/
├── src/
│   ├── cli/                 # CLI commands
│   │   ├── commands/        # Individual commands
│   │   ├── prompts.ts       # @clack/prompts helpers
│   │   └── index.ts         # CLI entry point
│   ├── config/              # Configuration system
│   │   ├── env.ts           # Environment variable resolver
│   │   ├── paths.ts         # Config path resolution
│   │   ├── schema.ts        # Valibot schema
│   │   └── index.ts         # Config manager
│   ├── providers/           # AI provider implementations
│   │   ├── google/          # Google Gemini
│   │   ├── kimi/            # Moonshot Kimi
│   │   ├── types.ts         # Provider interface
│   │   └── index.ts         # Provider registry
│   ├── tools/               # MCP tools
│   │   ├── handlers/        # Tool implementations
│   │   └── definitions.ts   # Tool definitions
│   ├── utils/               # Utilities
│   │   ├── video.ts         # Video validation
│   │   └── schemas.ts       # Valibot schemas
│   ├── types/               # TypeScript types
│   └── index.ts             # MCP server entry
├── package.json
├── tsconfig.json
├── biome.json
└── mcp.json                 # Example MCP client config

License

MIT