media-mcp
Provides tools for interacting with Radarr to look up and add movies, list the library, view the calendar, inspect the download queue, and trigger searches.
Provides tools for interacting with Sonarr to look up and add TV series, list the library, view the calendar and missing episodes, inspect the download queue, and trigger searches.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@media-mcp Add the movie Dune: Part Two to Radarr"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 syncor 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 keysVariable | Default | Notes |
|
| Sonarr › Settings › General |
|
| Radarr › Settings › General |
|
| Lidarr › Settings › General |
|
| SABnzbd › Config › General |
|
|
|
|
| HTTP timeout in seconds |
|
|
|
|
| only for |
| required for LAN access; | |
|
| 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-mcpClaude 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.
In the repo folder:
copy .env.example .env, then add your API keys to.env.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/mcpFor 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.
Generate a token:
uv run media-mcp new-token. Put the printed line in.env, along withMEDIA_MCP_HOST=0.0.0.0.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.
On the other computer, connect Claude Code. Replace
MEDIA-PCwith 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 userto make it available in every project. Check it withclaude mcp list.Claude Desktop can't send headers to an HTTP server directly. Install Node.js and bridge with
mcp-remoteinclaude_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_foldersSonarr:
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 pytestTests 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..envand 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 toolmedia_servicesARead-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
Scored across 1 tool
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.
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.
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.
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
Manage digital signage screens, playlists and media from your AI assistant.
Search MusicBrainz artists, releases, works, labels; resolve ISRC/ISWC/barcode; fetch cover art.
Manage SRG+ hubs, channels, content, assets, users, and workspaces from any MCP-aware AI agent.
Manage tickets, run agents and workflows, query tables, and search workspace knowledge.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables unified control of \*arr media management applications (Sonarr, Radarr, Lidarr, Readarr, Prowlarr) through natural language queries. Manage TV shows, movies, music, books, search for content, monitor downloads, and check upcoming releases across all services.732,281 npm247MIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Sonarr and Radarr APIs to query media libraries, check recent additions, view upcoming releases, manage download queues, and perform searches for TV shows and movies through natural language.1MIT
- FlicenseNot gradedqualityDmaintenanceIntegrates with Radarr and Sonarr to manage your media library, enabling search, download requests, status checks, and system health monitoring.6-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage media automation services like Sonarr, Radarr, Prowlarr, Bazarr, Overseerr, and Plex through natural language commands.8MIT