imdb-analytics-mcp

Local, personal MCP server that lets an LLM rank, compare and connect actors and titles from IMDb's non-commercial datasets, stored in DuckDB, with Wikidata enrichment.

Status (2026-09-09): M1 ingest, M2 analytics and M3 MCP tools are built. Wikidata enrichment (nationality, gender, awards) is M4 and those filters return an error until then.

Read in this order:

1. docs/brief.md — the original plan and definition of done.

2. docs/research.md — prior art survey and answers to the Phase 15 questions.

3. docs/storage-decision.md — DuckDB, measured against SQLite on the full data.

4. docs/data-model.md — tables, the configurable credit definition, unsupportable filters.

5. docs/architecture.md — layers, data flow, tool surface, milestones.

6. docs/scoring.md — recognition score: first measurement and planned experiments.

Detailed source research and benchmark reports live in docs/research/. Prototype scripts are in scripts/ (proto_* = raw-table load and DuckDB vs SQLite bench; proto2_* = the proposed schema bench). Data lives outside the repo under data/ (a symlink; gitignored).

Setup: uv sync, then uv run imdb-mcp update to download the datasets and build data/imdb.duckdb (about 4.4 GB). uv run imdb-mcp status says how fresh it is, uv run imdb-mcp doctor checks the environment.

Licensing and data

The software is MIT licensed. The IMDb datasets it downloads are not: IMDb permits them for personal, non-commercial use only, and forbids republishing them as a database of movie information. This project therefore runs locally, each user fetches the data themselves with imdb-mcp update, and nothing derived from IMDb data is redistributed. Do not host it as a shared service. Wikidata enrichment data is CC0.

Use with Claude Desktop or Claude Code

The server speaks MCP over stdio. Build the database first (uv run imdb-mcp update), then point a client at imdb-mcp serve.

Claude Desktop — add this to claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "imdb-analytics": {
      "command": "uv",
      "args": ["--directory", "/home/you/dev/imdb-analytics-mcp", "run", "imdb-mcp", "serve"],
      "env": { "IMDB_MCP_DATA_DIR": "/home/you/dev/imdb-analytics-mcp/data" }
    }
  }
}

Claude Code — one line:

claude mcp add imdb-analytics -- uv --directory /home/you/dev/imdb-analytics-mcp run imdb-mcp serve

imdb-mcp serve --transport http --port 8765 serves the same tools over HTTP, for MCP Inspector or any other debugging client. The server holds the database open, so after an imdb-mcp update the client has to reconnect before it sees the new data.

An example conversation

This is the brief's definition-of-done chain, run against the real build on 2026-09-09. The full output of every step, including each response's method and caveats, is in docs/summaries/m3-dod-chain-2026-09-09.md.

Who are the 25 people with the most acting credits?

Brahmanandam (1,131), Eric Roberts (725), Jagathy Sreekumar (653), Eddie Garcia (650), Adoor Bhasi (617)… — counting movies, TV movies, TV series, TV specials and direct-to-video titles, with a series counted once regardless of episode count, and self appearances, archive footage and adult titles excluded. 2,380,714 people have at least one credit.

Only the ones still alive.

15 of the 25. IMDb records a death year only when a death is known, so this really means "not known to have died".

Born before 1960, and sort them by how long their careers have run.

10 people. Aruna Irani leads at 68 years, then Jagathy Sreekumar (67), Frank Welker (66), Raza Murad (61), Shakti Kapoor (52), Eric Roberts (51)…

Which five of those have been in the most highly rated films?

Counting titles rated 7.0 or better with at least 1,000 votes: Frank Welker (103), Nassar (73), Tanikella Bharani (54), Brahmanandam (49), Anupam Kher (42).

Compare those five, and tell me which two have worked together most.

Frank Welker has by far the most votes across his filmography (4.9M) and the highest mean rating (6.75); Brahmanandam has the most credits (1,131) and the highest credits per year (28). Tanikella Bharani and Brahmanandam have appeared together 168 times.

What did those two make together?

Ghilli (2004, 8.2), Dookudu (2011, 7.4), Race Gurram (2014, 7.4), Khaleja (2010, 7.6), Bommarillu (2006, 8.2)… — 168 titles in all, most-voted first.

Every one of those turns is a single tool call whose arguments are the previous turn's arguments with one field changed, and each refinement passes the previous result's IMDb ids back in. The server keeps no session state.