cleanuparr-mcp

Part of the arr-mcps collection. An MCP server exposing Cleanuparr's REST API as tools for inspecting status, history, statistics, jobs, and configuration.

Requirements

• Cleanuparr with its REST API enabled

• An API key from Cleanuparr

• Python 3.11+ and uv for source development

Configuration

Install a built wheel and register it with Claude Code:

uv tool install cleanuparr_mcp-*.whl
claude mcp add cleanuparr \
  --env CLEANUPARR_URL=https://cleanuparr.example.com \
  --env CLEANUPARR_API_KEY=your-api-key \
  -- cleanuparr-mcp

For a source checkout:

uv sync
claude mcp add cleanuparr \
  --env CLEANUPARR_URL=https://cleanuparr.example.com \
  --env CLEANUPARR_API_KEY=your-api-key \
  -- uv run --directory /path/to/cleanuparr-mcp cleanuparr-mcp

Tools

8 resource-scoped tools, each covering multiple Cleanuparr REST endpoints (84 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. This keeps the full API surface available while costing a fraction of the context budget of registering all 84 endpoints as separate tools.

Example: cleanuparr_jobs(operation="cleanuparr_trigger_job", arguments={"job_type": "QueueCleaner"}). Endpoint-level naming (cleanuparr_<verb>_<resource>) is preserved as the operation value, so the full endpoint list is still discoverable from each group tool's description at runtime.

Destructive operations are noted in their operation-line doc. Cleanuparr returns 503 when its configuration database is busy; this server does not retry and instead returns the upstream error to the MCP client.

Request bodies are pass-through JSON dictionaries matching the DTOs in the running Cleanuparr version. Sensitive update fields should use Cleanuparr's placeholder value to preserve an existing secret. Do not place real API keys, passwords, or notification tokens in prompts.

Development

make sync
make test
make test-integration   # requires CLEANUPARR_URL and optionally CLEANUPARR_API_KEY
make build

The offline tests use httpx.MockTransport; integration tests are skipped by default.