tmdb-mcp

XDwanj/tmdb-mcp

3.2

If you are the rightful owner of tmdb-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

TMDB MCP Server is a Model Context Protocol server designed to interact with The Movie Database (TMDB) for retrieving movie and TV data.

Tools
6
Resources
0
Prompts
0

TMDB MCP Server

GitHub Stars License Go Version Release Docker Pulls

An MCP (Model Context Protocol) server for The Movie Database (TMDB): search, details, discovery, trending, and recommendations — ready for stdio and SSE modes, with Docker support.

|

Overview

TMDB MCP Server exposes six MCP tools so AI coding assistants and MCP clients (e.g., Claude Code) can search and retrieve movie/TV data from TMDB.

Quick Start

Prerequisites

Run (stdio mode)

TMDB_API_KEY=your_api_key go run ./cmd/tmdb-mcp --server-mode stdio

This starts the server over stdio. Connect with an MCP-compatible client via stdio transport.

Run (SSE mode)

# Option A: Let the app generate a token and persist to ~/.tmdb-mcp/config.yaml
TMDB_API_KEY=your_api_key \
SERVER_MODE=sse \
go run ./cmd/tmdb-mcp

# Option B: Provide your own token
TMDB_API_KEY=your_api_key \
SERVER_MODE=sse \
SSE_TOKEN=$(openssl rand -base64 32) \
go run ./cmd/tmdb-mcp

# Health check
curl -s http://localhost:8910/health

Docker

Option 1: Use pre-built image (Recommended)
docker pull ghcr.io/xdwanj/tmdb-mcp:latest
docker run --rm -p 8910:8910 \
  -e TMDB_API_KEY=your_api_key \
  -e SERVER_MODE=sse \
  -e SSE_TOKEN=$(openssl rand -base64 32) \
  ghcr.io/xdwanj/tmdb-mcp:latest
Option 2: Build from source
docker build -t tmdb-mcp .
docker run --rm -p 8910:8910 \
  -e TMDB_API_KEY=your_api_key \
  -e SERVER_MODE=sse \
  -e SSE_TOKEN=$(openssl rand -base64 32) \
  tmdb-mcp

Or use docker-compose: see examples/docker-compose.yml.

Binary Downloads

Pre-compiled binaries are available on the Releases page.

Supported platforms:

  • Linux (amd64, arm64)
  • macOS (amd64, arm64)
  • Windows (amd64)

Example:

# Linux amd64
wget https://github.com/XDwanj/tmdb-mcp/releases/latest/download/tmdb-mcp-linux-amd64.tar.gz
tar -xzf tmdb-mcp-linux-amd64.tar.gz
sudo mv tmdb-mcp /usr/local/bin/

Features

Exposed MCP tools:

  • search — Search movies/TV by query
  • get_details — Get details by media type and ID
  • discover_movies — Discover movies with rich filters
  • discover_tv — Discover TV with rich filters
  • get_trending — Trending items by media type and window
  • get_recommendations — Recommendations based on a movie/TV ID

Typical flows:

  • search → get_details
  • discover_movies → get_recommendations
  • get_trending → get_details

Configuration

Configuration sources and priority: CLI flags > Environment variables > Config file.

Flags (subset):

  • --tmdb-api-key, --tmdb-language, --tmdb-rate-limit
  • --server-mode, --sse-host, --sse-port, --sse-token
  • --logging-level

Environment variables (when flags are not provided):

  • TMDB_API_KEY, TMDB_LANGUAGE, TMDB_RATE_LIMIT
  • SERVER_MODE, SERVER_SSE_HOST, SERVER_SSE_PORT, SSE_TOKEN
  • LOGGING_LEVEL

Config file (fallback): ~/.tmdb-mcp/config.yaml See examples/config.yaml for a complete example.

Key fields:

  • tmdb.api_key, tmdb.language, tmdb.rate_limit
  • server.mode (stdio|sse|both), server.sse.host, server.sse.port, server.sse.token
  • logging.level

Deployment

Quick Deployment Options

  1. Pre-built Docker Image (Recommended):

    docker run -d --name tmdb-mcp -p 8910:8910 \
  -e TMDB_API_KEY=your_api_key \
  -e SERVER_MODE=sse \
  -e SSE_TOKEN=your_token \
  ghcr.io/xdwanj/tmdb-mcp:latest

  2. Download Binary:

    # Download the latest release for your platform
wget https://github.com/XDwanj/tmdb-mcp/releases/latest/download/tmdb-mcp-linux-amd64.tar.gz
tar -xzf tmdb-mcp-linux-amd64.tar.gz
./tmdb-mcp --server-mode sse

  3. Build from Source:

    go build -o tmdb-mcp ./cmd/tmdb-mcp
./tmdb-mcp --server-mode sse

Production Deployment

  • Docker Compose: See examples/docker-compose.yml
  • Kubernetes: Expose the container at port 8910 and configure SSE_TOKEN/TMDB_API_KEY via secrets
  • Docker Registry: Use ghcr.io/xdwanj/tmdb-mcp:{tag} for specific versions

Version Management

  • Use semantic versioning (e.g., v1.0.0, v1.0.1)
  • latest tag always points to the most recent stable release
  • For production, pin to a specific version tag (e.g., ghcr.io/xdwanj/tmdb-mcp:v1.0.0)

Use with Claude Code (MCP)

When running in SSE mode (for example at http://localhost:8910/mcp/sse) with an SSE_TOKEN, you can connect Claude Code via either of the following methods.

  • Option 1: Configure ~/.claude.json
{
  "mcpServers": {
    "tmdb-mcp-sse": {
      "type": "sse",
      "url": "http://localhost:8910/mcp/sse",
      "headers": {
        "Authorization": "Bearer xxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
  • Option 2: Use the Claude CLI
claude mcp add --transport sse tmdb-mcp-sse \
  http://localhost:8910/mcp/sse \
  --header "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx" \
  --scope user
  • Verify installation
claude mcp list

Replace the placeholder token with your actual SSE_TOKEN, and adjust the URL if the server runs on a different host/port.

Development

  • Format: go fmt ./...
  • Vet: go vet ./...
  • Test: go test ./...
  • Lint (Markdown): run your preferred linter locally (e.g., markdownlint)
  • Code style and structure: see docs/architecture/coding-standards.md and docs/architecture/source-tree.md

Contributing

  1. Open an issue to discuss changes
  2. Fork and create a feature branch
  3. Add tests and docs
  4. Submit a PR for review

License

TBD. Please add a LICENSE file (e.g., MIT) to this repository.

Acknowledgements