Metadata-Version: 2.4
Name: imdb-mcp-server
Version: 0.1.0
Summary: MCP server for IMDb movie data (via OMDb) with a personal movie memory: ratings, watchlist, and taste-based recommendations
Project-URL: Homepage, https://github.com/abdullahh-sheikhh/imdb-mcp-server
Author-email: Abdullah Sheikh <abdullah38891@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,imdb,mcp,model-context-protocol,movies,omdb
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2
Description-Content-Type: text/markdown

# imdb-mcp-server

An MCP (Model Context Protocol) server exposing IMDb movie data (via the
[OMDb API](https://www.omdbapi.com/)) 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):

| Tool | Input | Returns |
|---|---|---|
| `search_movies` | `query`, optional `year`, `type` | Matches with title, year, IMDb ID |
| `get_movie_details` | `imdb_id` | Plot, director, cast, genre, ratings |
| `get_movie_ratings` | `imdb_id` | IMDb / Rotten Tomatoes / Metacritic scores |

Personal memory (local SQLite):

| Tool | What it does |
|---|---|
| `log_movie` | Record watched/watchlist + liked/disliked + optional 1–10 rating |
| `get_my_movies` | List history or watchlist |
| `get_taste_profile` | Genre preferences, likes/dislikes, avg rating — feeds recommendations |
| `remove_movie` | Delete an entry |

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

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

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

Debug with the MCP Inspector:

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