# 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:

```json
{
  "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`](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.