moviefinder-mcp

An MCP server that wraps The Movie Database (TMDB) API. Built with @modelcontextprotocol/sdk and stdio transport.

Tools

All tools return summarized JSON (id, title, year, overview, rating, poster URL, etc.) — the noisy raw TMDB fields are stripped.

Setup

1. Get a TMDB API token

1. Create a free account at https://www.themoviedb.org/.

2. Visit https://www.themoviedb.org/settings/api and copy the API Read Access Token (v4). This is a long JWT — it is not the v3 API key.

2. Install and build

npm install
npm run build

3. Configure environment

Copy .env.example to .env and paste your token:

cp .env.example .env

TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...

4. Run the server

npm start

The server speaks MCP over stdio and is meant to be launched by an MCP client (such as Claude Desktop), not run interactively.

Register with Claude Desktop

Add an entry to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "moviefinder": {
      "command": "node",
      "args": ["/absolute/path/to/moviefinder-mcp/dist/index.js"],
      "env": {
        "TMDB_API_KEY": "eyJhbGciOi...your_v4_read_access_token..."
      }
    }
  }
}

Restart Claude Desktop after editing the config. The moviefinder tools will then appear in any conversation.

Scripts

Error handling

The server returns helpful messages for common TMDB failures:

• 401 — token missing or wrong key type (must be v4 read access token).

• 404 — the requested movie / resource does not exist.

• 429 — rate limited; the Retry-After value is included when present.

Notes

• Genre list is fetched once from /genre/movie/list and cached in memory.

• Poster URLs use https://image.tmdb.org/t/p/w500.

• No database, no logging framework — by design.