mcparr

MCPify your *arr stack. mcparr is a self-hosted Model Context Protocol gateway that lets AI assistants (Claude, ChatGPT, GitHub Copilot, Cursor, ...) drive your media services - Radarr, Sonarr, and more - through a single, authenticated MCP endpoint.

What it does

mcparr runs as one Docker container exposing two ports:

• 7475 - config UI: a small web app to add service connections, test them, toggle tools, and copy the MCP connection details. Protected by an admin password.

• 7474 - MCP endpoint: a Streamable HTTP MCP server that AI clients connect to. Always requires a bearer token.

Each enabled service contributes a set of namespaced tools (for example radarr_search_movies, sonarr_list_series). Toggling a service in the UI adds or removes its tools live, without restarting the container.

Related MCP server: homelab-ai

Status

Early development. The v1 surface ships the gateway core plus Radarr and Sonarr; more services (Prowlarr, Plex, Overseerr/Seerr, Maintainerr, Lidarr) are planned.

Quick start

docker compose up -d

Then:

1. Open http://localhost:7475 and set an admin password.

2. Add a service (base URL + API key), test the connection, and enable it.

3. Open the Connect page to copy the MCP URL and bearer token into your AI client.

The config UI is published on localhost only by default. The MCP endpoint is exposed but always requires the token.

Connecting a client (VS Code / GitHub Copilot)

{
  "servers": {
    "mcparr": {
      "type": "http",
      "url": "http://your-host:7474/mcp",
      "headers": { "Authorization": "Bearer <token-from-connect-page>" }
    }
  }
}

For Claude Desktop, use the mcp-remote bridge (snippet on the Connect page). Hosted connectors (Claude.ai, ChatGPT) require HTTPS - put mcparr behind a TLS reverse proxy.

Release channels

The image is published to GHCR under three rolling tags. Set image: in docker-compose.yml to the channel you want:

For reproducible deployments, pin an exact version instead - for example ghcr.io/phillyurbs/mcparr:0.1.1. Stable releases also publish the moving :0, :0.1 major/minor tags.

Configuration

All state lives in the /data volume (SQLite database, encryption key, MCP token, audit log). Useful environment variables:

You can pre-populate services declaratively with a seed file - see config.yaml.example.

Security

The MCP endpoint always requires a token; the UI always requires a password. Service keys are encrypted at rest. See SECURITY.md and the threat model for details.

Development

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest -q
ruff check .
python -m mcparr.main   # runs both servers locally

Translations are managed with Babel (babel.cfg); compile catalogs with pybabel compile -d mcparr/ui/locales -D messages.

Branch workflow

Work on a short-lived branch and open a pull request into main; CI runs on the PR. No :dev image is built from branch pushes, so committing early and often is harmless. Merging the PR into main produces one :dev build (squash-merge keeps history tidy). Add [skip ci] to a commit message to skip workflows for that commit, and docs-only changes (Markdown, docs/, LICENSE) never trigger an image build.

Cutting a release

Releases are version-free for you: the Release workflow computes the next version, tags the commit, and builds the channel image.

1. Open the Actions tab (or the GitHub Actions panel in VS Code) and run the Release workflow.

2. Pick a channel (beta or stable) and a bump (auto by default).

3. The workflow tags the commit and publishes the image.

With bump = auto:

• beta patch-bumps the latest stable and starts/continues a -beta.N series - v0.1.0 -> v0.1.1-beta.1 -> v0.1.1-beta.2 -> ...

• stable promotes an in-flight beta (v0.1.1-beta.2 -> v0.1.1), or patch- bumps if no beta is pending.

Use bump = minor or major to override the base when a release is bigger than a patch. The version math lives in scripts/next_version.py and is covered by tests/test_next_version.py.

Adding a service

Create a ServiceModule subclass under mcparr/services/, declare its metadata and tools, and decorate it with @register. The base class provides the HTTP client, pagination, result shaping, and error mapping. Radarr and Sonarr are the reference implementations.

License

See LICENSE.