profilarr-mcp

Part of the arr-mcps collection. MCP server exposing Profilarr's v1 REST API (/api/v1, OpenAPI 3.1) as tools, so an LLM can inspect and manage your Profilarr instance: linked databases, connected Radarr/Sonarr instances, backups, jobs, announcements, and system status.

Built with FastMCP.

Scope

Profilarr's programmatic API is deliberately small. This server wraps the documented /api/v1 JSON surface only:

• System — health, status, OpenAPI spec

• Arr — list connected instances (read-only; sync state via status)

• Databases — link/get/update/unlink, trigger PCD sync

• Jobs — poll job status

• Backups — list/create/download/upload/delete/settings

• Announcements — list/get

Many of Profilarr's headline features (custom formats, quality profiles, regular expressions, delay profiles, media management, upgrades, rename, notifications, and triggering an Arr sync) are not exposed by the v1 REST API — they live behind SvelteKit form actions that require a browser session and CSRF token, so they are intentionally not wrapped here. Use the web UI for those.

Related MCP server: mcp-arrstack

Getting the API key

Profilarr accepts X-Api-Key on every /api/v1 request. The active key is either the PROFILARR_API_KEY environment variable set on the Profilarr server (≥ 32 characters, takes precedence), or the key generated under Settings > Security in the web UI (bcrypt-stored, shown once). /health is the only endpoint that works without a key.

Install

Download a wheel from the latest release and install it as a uv tool (no repo checkout needed):

uv tool install profilarr_mcp-*.whl

This puts a profilarr-mcp command on your PATH. Register it with Claude Code:

claude mcp add profilarr \
  --env PROFILARR_URL=https://your-profilarr-host \
  --env PROFILARR_API_KEY=<key> \
  -- profilarr-mcp

From source

uv sync
cp .env.example .env   # fill in PROFILARR_URL and PROFILARR_API_KEY

claude mcp add profilarr \
  --env PROFILARR_URL=https://your-profilarr-host \
  --env PROFILARR_API_KEY=<key> \
  -- uv run --directory /path/to/profilarr-mcp profilarr-mcp

Config

*Required for every tool except profilarr_health, which is public.

Tools

4 resource-scoped tools, each covering multiple Profilarr v1 endpoints (20 total) via an operation parameter. Call a tool with operation set to one of its listed operations and an arguments dict matching that operation's parameters — the tool's own description (visible to your MCP client) lists every operation, its signature, and a one-line doc.

Example: profilarr_databases(operation="profilarr_sync_database", arguments={"id": 3}). Endpoint-level naming (profilarr_<verb>_<resource>) is preserved as the operation value:

Async jobs

profilarr_create_backup and profilarr_sync_database return {jobId} with HTTP 202. Poll the result with profilarr_jobs_arr(operation="profilarr_get_job", arguments={"id": jobId}). Note profilarr_sync_database pulls the linked database repo, not an Arr sync.

Binary endpoints

profilarr_download_backup streams the sanitized archive to a local temp file (PROFILARR_TEMP_DIR or the system temp dir) and returns {path, filename, size}. profilarr_upload_backup takes a local file path and POSTs it as multipart form data. Bytes never enter the LLM context.

Development

make help  # list all commands

The release workflow (.github/workflows/release.yml) builds and publishes to Releases whenever a v* tag is pushed — so the usual flow is make bump-patch, commit, then tag and push.

The integration suite is read-only (health/status/arr/databases/announcements) plus a self-cleaning backup lifecycle (create → poll → download → delete). Database create/delete is intentionally not exercised against a live instance, since linking a database clones a real repository.