An MCP server for The Movie Database (TMDB) API. It provides movie and TV search, streaming availability, cast and crew details, and recommendations for assistants such as Codex and Claude Desktop.

• search_movies — Search by title/keywords → titles, IDs, ratings, overviews
• get_trending — Top 10 trending movies (timeWindow: "day" | "week")
• search_by_genre — Movies by genre name, optional year filter
• advanced_search — Filter by genre, year, min rating, sort, language
• search_by_keyword — Find movies by theme/keyword (e.g. "zombie", "heist")

• get_movie_details — Full details: cast, crew, runtime, genres, reviews (by movieId)
• get_recommendations — Top 5 recommendations based on a movie ID
• get_similar_movies — Similar movies via TMDB's similarity algorithm
• get_watch_providers — Streaming/rental/purchase availability by country (default: IN)

• search_tv_shows — Search TV series by title
• get_trending_tv — Top 10 trending TV shows (timeWindow: "day" | "week")

• search_person — Find actors, directors, crew by name → ID + known works
• get_person_details — Full bio + filmography (movies + TV) by personId

• tmdb:///movie/<id> — Full movie details in JSON (title, cast, director, reviews, poster URL)

1. Get a TMDB API key at themoviedb.org → Account Settings → API

2. Clone, install, and build:

   git clone https://github.com/Laksh-star/mcp-server-tmdb.git
   cd mcp-server-tmdb
   npm install

3. Create a local env file and add your TMDB key:

   cp .env.example .env

4. Install the local Codex and Claude Desktop integration:

   npm run install:local

5. Restart Codex or Claude Desktop if already open.

6. Verify with a prompt like:

   What movies are trending this week?
   

In Codex, a fresh session should show TMDB in the plugin list and expose the mcp__tmdb__ namespace.

The installer uses the repo-owned launcher at plugins/tmdb/scripts/run-server.sh.

For Codex it:

• Registers the launcher as an MCP server
• Installs a local TMDB plugin payload so it appears in the plugin UI

For Claude Desktop it:

• Registers the same launcher as a local MCP server

It updates:

• ~/.codex/config.toml
• ~/.codex/.tmp/plugins/.agents/plugins/marketplace.json
• ~/.codex/plugins/cache/openai-curated/tmdb/...
• ~/Library/Application Support/Claude/claude_desktop_config.json

The launcher reads TMDB_API_KEY from your shell environment or from the repo .env file.

If you prefer manual setup, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tmdb-local": {
      "command": "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh",
      "args": []
    }
  }
}

Restart Claude Desktop after editing the config.

The installer adds these blocks to ~/.codex/config.toml:

[mcp_servers.tmdb_local]
command = "/full/path/to/mcp-server-tmdb/plugins/tmdb/scripts/run-server.sh"

[plugins."tmdb@openai-curated"]
enabled = true

Restart Codex after editing the config. In a fresh Codex session, TMDB should appear in the plugin list and contribute the mcp__tmdb__ namespace.

Offline smoke test:

TMDB_API_KEY=dummy node plugins/tmdb/scripts/smoke-test.mjs

Online smoke test:

set -a && source ./.env && set +a && node plugins/tmdb/scripts/smoke-test.mjs --online

For plugin packaging, local install behavior, and Codex-specific notes, see plugins/tmdb/README.md.

Built into the agent container. Just set TMDB_API_KEY in your .env file — no configuration needed.

"What's trending in movies this week?"
"Find me Thriller movies from 2023"
"Who is Christopher Nolan and what has he directed?"
"Where can I watch Inception in India?"
"Get details for movie ID 550 (Fight Club)"
"Find movies similar to Interstellar"
"What are the trending TV shows right now?"

MIT