MediaLLM MCP Server

MCP server that provides AI-powered media processing capabilities for FFmpeg operations through natural language commands. MediaLLM converts natural language requests into precise FFmpeg commands and scans workspaces for media files.

Full Documentation

Installation

# Using pip
pip install mediallm-mcp

# Using uv (recommended)
uv add mediallm-mcp

Usage

# STDIO (default)
mediallm-mcp

# Streamable HTTP (default path: /mcp)
mediallm-mcp --http --port 3001

# SSE
mediallm-mcp --sse --port 3001

# Optional: customize MCP HTTP endpoint path (default: /mcp)
mediallm-mcp --http --port 3001 --path /api/mcp

Running in Docker

# Build image
cd packages/mediallm-mcp
docker build -t mediallm-mcp .

# Run with media directory mounted and HTTP port exposed
docker run -it --rm \
  -p 8080:8080 \
  -v /path/to/media:/workspace \
  mediallm-mcp

# MCP endpoint (default): http://localhost:8080/mcp

Accessing from Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mediallm-mcp": {
      "command": "uvx",
      "args": ["mediallm-mcp"],
      "env": {}
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Accessing from Claude Code

Add to .mcp.json in project root:

{
  "mcpServers": {
    "mediallm-mcp": {
      "command": "uvx",
      "args": ["mediallm-mcp"],
      "env": {}
    }
  }
}

Accessing from Cursor

Or manually add to .cursor/mcp.json:

{
  "mcpServers": {
    "mediallm-mcp": {
      "command": "uvx",
      "args": ["mediallm-mcp"],
      "env": {}
    }
  }
}

Environment Variables (Optional) for MCP configuration

• MEDIALLM_WORKSPACE - Specify media directory (default: current working directory)
• MEDIALLM_MODEL - Override LLM model (default: llama3.1:latest)
• MEDIALLM_OLLAMA_HOST - Ollama server URL (default: http://localhost:11434)
• MEDIALLM_OUTPUT_DIR - Output directory (default: current working directory)

Debugging

Use MCP inspector to test the connection:

1. Activate virtual environment

cd packages/mediallm-mcp && uv sync --all-extras && source .venv/bin/activate

2. Run MCP inspector

npx @modelcontextprotocol/inspector mediallm-mcp

MCP Inspector: Request timed out (-32001)

If testing long-running tools like generate_command results in an error such as: "MCP error -32001: Request timed out", increase the Inspector client timeouts in its Configuration panel:

• Request Timeout: 300000 (5 minutes)
• Reset Timeout on Progress: true
• Maximum Total Timeout: 900000 (15 minutes)

These values follow MCP guidance to allow configurable per-request timeouts and to optionally reset timeouts on progress while still enforcing a maximum overall timeout. See the MCP spec section on timeouts and the Inspector discussion about default client timeouts for context.

• Spec: MCP Lifecycle – Timeouts
• Inspector discussion: Set longer request times for Inspector client