omdb-mcp

An MCP (Model Context Protocol) server for the OMDb API — search movies, series, and episodes from any MCP-compatible client.

Built with FastMCP. Supports both STDIO and Streamable HTTP transports, with optional bearer-token auth for HTTP mode.

Features

Five tools: search_movies, get_by_title, get_by_imdb_id, get_episode, get_season
Dual transport: STDIO (for MetaMCP / Claude Desktop / Hermes) and Streamable HTTP (for standalone agents)
Optional bearer-token authentication for HTTP mode
Configuration via .env or environment variables
Minimal dependencies: fastmcp, httpx, python-dotenv

Install

# Recommended: run directly with uvx (no install needed)
uvx omdb-mcp

# Or install into your environment
pip install omdb-mcp

Get a free OMDb API key at https://www.omdbapi.com/apikey.aspx (1,000 requests/day on the free tier).

Configuration

All settings come from environment variables (a .env file in the working directory is auto-loaded).

Variable	Default	Description
`OMDB_API_KEY`	(required)	Your OMDb API key
`OMDB_MCP_TRANSPORT`	`stdio`	`stdio` or `http`
`OMDB_MCP_HOST`	`127.0.0.1`	HTTP bind address (`0.0.0.0` for LAN/Docker)
`OMDB_MCP_PORT`	`8087`	HTTP port
`OMDB_MCP_PATH`	`/mcp`	HTTP mount path
`OMDB_MCP_AUTH_TOKEN`	(unset)	If set, HTTP clients must send `Authorization: Bearer ...`
`OMDB_MCP_LOG_LEVEL`	`INFO`	`DEBUG`, `INFO`, `WARNING`, `ERROR`
`OMDB_REQUEST_TIMEOUT`	`10`	OMDb HTTP timeout (seconds)
`OMDB_BASE_URL`	`https://www.omdbapi.com/`	Override only if proxying/mirroring OMDb

See .env.example for a copy-paste template.

Running

STDIO mode (for MCP clients that spawn the process)

omdb-mcp
# or with uv:
uvx omdb-mcp

Streamable HTTP mode (for standalone, long-lived service)

omdb-mcp-http
# or override port/host:
omdb-mcp-http --port 8087 --host 0.0.0.0

CLI flags --transport, --host, --port, --path override env vars.

Client setup

MetaMCP

Option A — STDIO (simplest, no service to manage):

Type: STDIO
Command: uvx
Args: omdb-mcp
Env: OMDB_API_KEY=your_key_here

Option B — Streamable HTTP (standalone service):

Run the server on the host:

OMDB_API_KEY=your_key OMDB_MCP_AUTH_TOKEN=mysecret omdb-mcp-http

In MetaMCP:

Type: Streamable HTTP
URL: http://host.docker.internal:8087/mcp
Header: Authorization: Bearer mysecret (if OMDB_MCP_AUTH_TOKEN is set)

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "omdb": {
      "command": "uvx",
      "args": ["omdb-mcp"],
      "env": {
        "OMDB_API_KEY": "your_key_here"
      }
    }
  }
}

Cursor / Windsurf / Cline

Same JSON shape, different config path. Cursor reads ~/.cursor/mcp.json:

{
  "mcpServers": {
    "omdb": {
      "command": "uvx",
      "args": ["omdb-mcp"],
      "env": { "OMDB_API_KEY": "your_key_here" }
    }
  }
}

Generic Streamable HTTP client

{
  "mcpServers": {
    "omdb": {
      "url": "http://127.0.0.1:8087/mcp",
      "headers": {
        "Authorization": "Bearer your_token_here"
      }
    }
  }
}

Tools

Tool	OMDb param(s)	Description
`search_movies`	`s`, `y`, `type`, `page`	Free-text search (paginated, 10 per page)
`get_by_title`	`t`, `y`, `type`, `plot`	Lookup by exact title
`get_by_imdb_id`	`i`, `plot`	Lookup by IMDb ID (`tt...`)
`get_episode`	`i`/`t`, `Season`, `Episode`, `plot`	Single TV episode
`get_season`	`i`/`t`, `Season`	All episodes in a season

Running as a service (HTTP mode)

macOS — launchd

Create ~/Library/LaunchAgents/com.dworf.omdb-mcp.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key><string>com.dworf.omdb-mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOU/.local/bin/uvx</string>
        <string>omdb-mcp-http</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>OMDB_API_KEY</key><string>your_key_here</string>
        <key>OMDB_MCP_AUTH_TOKEN</key><string>your_token_here</string>
        <key>OMDB_MCP_HOST</key><string>127.0.0.1</string>
        <key>OMDB_MCP_PORT</key><string>8087</string>
    </dict>
    <key>RunAtLoad</key><true/>
    <key>KeepAlive</key><true/>
    <key>StandardOutPath</key><string>/tmp/omdb-mcp.log</string>
    <key>StandardErrorPath</key><string>/tmp/omdb-mcp.err</string>
</dict>
</plist>

Load it:

launchctl load ~/Library/LaunchAgents/com.dworf.omdb-mcp.plist
# stop / unload:
launchctl unload ~/Library/LaunchAgents/com.dworf.omdb-mcp.plist

Linux — systemd

Create ~/.config/systemd/user/omdb-mcp.service:

[Unit]
Description=OMDb MCP server (Streamable HTTP)
After=network.target

[Service]
ExecStart=%h/.local/bin/uvx omdb-mcp-http
Environment=OMDB_API_KEY=your_key_here
Environment=OMDB_MCP_AUTH_TOKEN=your_token_here
Environment=OMDB_MCP_HOST=127.0.0.1
Environment=OMDB_MCP_PORT=8087
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now omdb-mcp
systemctl --user status omdb-mcp
journalctl --user -u omdb-mcp -f

Docker

FROM python:3.12-slim
RUN pip install --no-cache-dir omdb-mcp
EXPOSE 8087
ENV OMDB_MCP_HOST=0.0.0.0 OMDB_MCP_PORT=8087
CMD ["omdb-mcp-http"]

docker build -t omdb-mcp .
docker run -d --name omdb-mcp -p 8087:8087 \
  -e OMDB_API_KEY=your_key \
  -e OMDB_MCP_AUTH_TOKEN=your_token \
  --restart unless-stopped omdb-mcp

Development

git clone https://github.com/Dworf/omdb-mcp
cd omdb-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest

Security note

If you bind to 0.0.0.0 without setting OMDB_MCP_AUTH_TOKEN, anyone on the network can use your OMDb API key. The server logs a warning at startup in that case — set a token in any non-localhost deployment.

Changelog

v0.1.0 — 2026-05-14

Initial release.
Five tools: search_movies, get_by_title, get_by_imdb_id, get_episode, get_season.
Dual transport: STDIO (default) and Streamable HTTP.
Optional bearer-token auth for HTTP mode.
.env loading via python-dotenv.
20 unit tests; smoke-tested against the live OMDb API.

Acknowledgements

OMDb API — Brian Fritz's free movie/series database. If you use this MCP server in production, please consider donating to OMDb or upgrading to a Patreon-tier key.
FastMCP — the Python MCP framework this server is built on.
Model Context Protocol — the open protocol that makes this possible.

License

MIT

omdb-mcp

omdb-mcp

Features

Install

Configuration

Running

STDIO mode (for MCP clients that spawn the process)

Streamable HTTP mode (for standalone, long-lived service)

Client setup

MetaMCP

Claude Desktop

Cursor / Windsurf / Cline

Generic Streamable HTTP client

Tools

Running as a service (HTTP mode)

macOS — launchd

Linux — systemd

Docker

Development

Security note

Changelog

v0.1.0 — 2026-05-14

Acknowledgements

License

Latest Blog Posts

MCP directory API