imdb-mcp-server

An MCP (Model Context Protocol) server exposing IMDb movie data (via the OMDb API) as tools an LLM can call.

Built as a learning project: two layers, deliberately separated.

Claude Code (MCP client)
      │  stdio (JSON-RPC)
      ▼
server.py   ← MCP layer: FastMCP server, 7 tools, formats results for an LLM
omdb.py     ← data layer: async httpx client for OMDb (knows nothing of MCP)
store.py    ← persistence: SQLite movie memory (knows nothing of MCP or OMDb)
movies.db   ← your personal taste data, local only (gitignored)

Tools

IMDb data (via OMDb):

Personal memory (local SQLite):

Recommendations work as a collaboration: the LLM reads your taste profile, generates candidates from its own movie knowledge, then verifies each with get_movie_details before suggesting.

Quick start

1. Get a free API key at https://www.omdbapi.com/apikey.aspx (activate via the email link).
2. Add to your MCP client config (e.g. .mcp.json for Claude Code, or claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "imdb": {
      "command": "uvx",
      "args": ["imdb-mcp-server"],
      "env": { "OMDB_API_KEY": "your-key-here" }
    }
  }
}

No uv? Use pip install imdb-mcp-server and set "command": "imdb-mcp-server".

Your movie memory is stored at ~/.imdb-mcp-server/movies.db (override with the IMDB_MCP_DB env var).

Development

python -m venv .venv
.venv/Scripts/pip install -e .

Debug with the MCP Inspector:

npx @modelcontextprotocol/inspector -e OMDB_API_KEY=<key> -- .venv/Scripts/python.exe -m imdb_mcp_server.server