Skip to main content
Glama

media-mcp

One Model Context Protocol server for a home media stack:

Service

What you can do

Sonarr (TV)

look up and add series, list library, calendar, missing episodes, queue, trigger searches

Radarr (movies)

look up and add movies, list library, calendar, queue, trigger searches

Lidarr (music)

look up and add artists, list library, calendar, missing albums, queue, trigger searches

SABnzbd (downloads)

current status and queue, history, warnings, pause/resume

It is designed to run on the same machine as those apps and talk to them over localhost.

Why one server?

Each service is a separate tool group that is only switched on when its API key is set. You get one process and one config file, and you can still run with any subset (say, just Sonarr and SABnzbd). Tool names are prefixed (sonarr_*, radarr_*, lidarr_*, sabnzbd_*) so the model can tell them apart.

Related MCP server: Sonarr & Radarr MCP Server

Install

Requires Python 3.10+. With uv:

git clone https://github.com/<you>/media-mcp.git
cd media-mcp
uv sync

or with pip: pip install .

Configure

All configuration is via environment variables. The easiest way is a local .env file, which is gitignored so your keys never end up in the repo:

cp .env.example .env
# then edit .env and paste in your API keys

Variable

Default

Notes

SONARR_URL / SONARR_API_KEY

http://localhost:8989

Sonarr › Settings › General

RADARR_URL / RADARR_API_KEY

http://localhost:7878

Radarr › Settings › General

LIDARR_URL / LIDARR_API_KEY

http://localhost:8686

Lidarr › Settings › General

SABNZBD_URL / SABNZBD_API_KEY

http://localhost:8080

SABnzbd › Config › General

MEDIA_MCP_READ_ONLY

false

true hides every tool that changes something

MEDIA_MCP_TIMEOUT

30

HTTP timeout in seconds

MEDIA_MCP_TRANSPORT

stdio

stdio or streamable-http

MEDIA_MCP_HOST / MEDIA_MCP_PORT

127.0.0.1 / 8765

only for streamable-http; 0.0.0.0 for LAN access

MEDIA_MCP_BEARER_TOKEN

required for LAN access; uv run media-mcp new-token

MEDIA_MCP_ENV_FILE

./.env

path to an alternative env file

A service with no API key is simply disabled. Variables already set in the environment win over .env.

Use with Claude

Claude Code (from the repo directory):

claude mcp add media -- uv run --directory /path/to/media-mcp media-mcp

Claude Desktop: add to claude_desktop_config.json:

{
  "mcpServers": {
    "media": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/media-mcp", "media-mcp"],
      "env": { "MEDIA_MCP_ENV_FILE": "/path/to/media-mcp/.env" }
    }
  }
}

Over HTTP: set MEDIA_MCP_TRANSPORT=streamable-http and run uv run media-mcp; the endpoint is http://127.0.0.1:8765/mcp. This has no authentication of its own, so keep it bound to 127.0.0.1 or put it behind something that does authenticate.

Run as a Windows service

To keep the server running in the background on Windows, install it as a service. It then serves streamable HTTP on 127.0.0.1 (port MEDIA_MCP_PORT, default 8765) and starts with Windows.

  1. In the repo folder: copy .env.example .env, then add your API keys to .env.

  2. From an elevated PowerShell in the repo folder:

    powershell -ExecutionPolicy Bypass -File scripts\windows\install-service.ps1

The script finds uv (or downloads a pinned, hash-checked copy into .tools\), builds the environment (Python is kept inside the repo in .python\), downloads a pinned, hash-checked WinSW into service\, registers a media-mcp service that restarts on failure, restricts .env to SYSTEM, Administrators and you, and checks that the endpoint answers. Logs are in service\logs\. Re-run it after git pull to update. To remove the service: scripts\windows\uninstall-service.ps1 (also elevated).

Then connect Claude Code with:

claude mcp add --transport http media http://127.0.0.1:8765/mcp

For Claude Desktop, which launches stdio servers, bridge to the HTTP endpoint with mcp-remote: {"command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:8765/mcp"]}.

Use from other computers on your network

The server can be shared with other devices on your home network. It isn't reachable from the internet.

  1. Generate a token: uv run media-mcp new-token. Put the printed line in .env, along with MEDIA_MCP_HOST=0.0.0.0.

  2. Re-run the Windows service installer. It adds a firewall rule that allows the port only from your local subnet, and only on networks marked Private or Domain. Without a token, the server refuses to listen beyond localhost.

  3. On the other computer, connect Claude Code. Replace MEDIA-PC with the server's name or IP address (the installer prints it) and use the token from .env:

    claude mcp add --transport http media http://MEDIA-PC:8765/mcp \
      --header "Authorization: Bearer <your MEDIA_MCP_BEARER_TOKEN>"

    Add --scope user to make it available in every project. Check it with claude mcp list.

    Claude Desktop can't send headers to an HTTP server directly. Install Node.js and bridge with mcp-remote in claude_desktop_config.json (Settings › Developer › Edit Config):

    {
      "mcpServers": {
        "media": {
          "command": "npx",
          "args": ["-y", "mcp-remote@0.15.2", "http://MEDIA-PC:8765/mcp",
                   "--allow-http", "--header", "Authorization:${AUTH_HEADER}"],
          "env": { "AUTH_HEADER": "Bearer <your MEDIA_MCP_BEARER_TOKEN>" }
        }
      }
    }

Traffic on the LAN is plain HTTP. Anyone on your network who can capture traffic could read the token, so only do this on a network you trust.

Claude on mobile and claude.ai custom connectors connect from Anthropic's cloud, not from your device, so they can't reach a server that is only on your LAN.

Tools

Call media_services to see which groups are active.

  • Common to Sonarr/Radarr/Lidarr: *_system_status (version + health), *_queue, *_quality_profiles, *_root_folders

  • Sonarr: sonarr_lookup_series, sonarr_list_series, sonarr_calendar, sonarr_missing, sonarr_add_series✎, sonarr_search_series✎

  • Radarr: radarr_lookup_movie, radarr_list_movies, radarr_calendar, radarr_add_movie✎, radarr_search_movie✎

  • Lidarr: lidarr_lookup_artist, lidarr_list_artists, lidarr_calendar, lidarr_missing, lidarr_metadata_profiles, lidarr_add_artist✎, lidarr_search_artist✎

  • SABnzbd: sabnzbd_status, sabnzbd_history, sabnzbd_warnings, sabnzbd_pause✎, sabnzbd_resume✎

✎ = changes something; hidden when MEDIA_MCP_READ_ONLY=true. Nothing in this server deletes media.

Development

uv sync --extra dev
uv run pytest

Tests use a fake HTTP backend, so no real services or keys are needed.

Security notes

  • Keys are read only from the environment / .env; they are never logged or returned by tools.

  • .env and other local config files are in .gitignore. Don't commit them.

  • The API keys give full control of each app, so treat the machine running this server accordingly.

License

MIT

Available Tools

1 tool
media_servicesA
Read-only

Which media services are configured, and whether write tools are enabled.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 1 tool

    Disambiguation4/5

    With only one tool there is no risk of selecting the wrong one, so ambiguity is essentially eliminated. However, the description is a question rather than an action, leaving it slightly unclear whether the tool merely reports configuration or also enumerates services/write capabilities.

    Naming Consistency3/5

    The single name 'media_services' is a noun phrase rather than a verb_noun action pattern (e.g. list_media_services, get_config). It is readable and unambiguous, but with one tool no consistent convention can be established.

    Tool Count2/5

    A server named media-mcp with exactly one tool is a poor scope fit; the only capability is a configuration/diagnostic check. The server implies media operations (list, upload, search, manage), which a single tool cannot represent.

    Completeness1/5

    The surface exposes no media lifecycle operations at all — no listing, retrieval, upload, or write actions, even though the tool references 'write tools' that don't exist here. Agents hitting this server for media work have no functional path forward.

    Related MCP Connectors

    Related MCP Servers