cleanuparr-mcp
Part of the arr-mcps collection.An MCP server exposing Cleanuparr'sREST API as tools for inspecting status, history, statistics, jobs, andconfiguration.
Requirements
- Cleanuparr with its REST API enabled
- An API key from Cleanuparr
- Python 3.11+ and
uvfor source development
Configuration
| Variable | Required | Description |
|---|---|---|
CLEANUPARR_URL |
Yes | Cleanuparr URL, including any reverse-proxy BASE_PATH; the server appends /api. |
CLEANUPARR_API_KEY |
Usually | API key sent as X-Api-Key. Health endpoints can be used without it when permitted. |
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 toone of its listed operations and an arguments dict matching thatoperation's parameters — the tool's own description (visible to your MCPclient) lists every operation, its signature, and a one-line doc. This keepsthe full API surface available while costing a fraction of the contextbudget of registering all 84 endpoints as separate tools.
| Tool | Operations | Covers |
|---|---|---|
cleanuparr_cleaner_config |
19 | Queue/download cleaners, dead torrents, orphaned/unlinked files, seeding rules |
cleanuparr_events |
18 | Events, manual events, strikes, timelines, stats |
cleanuparr_arr_download_clients |
15 | General config, *arr instances, download clients |
cleanuparr_health_status |
8 | Health, readiness, system/*arr/download-client status |
cleanuparr_stats |
7 | Seeker search events, custom-format scores |
cleanuparr_notifications |
6 | Notification providers |
cleanuparr_feature_configs |
6 | Malware blocker, Seeker, blacklist sync |
cleanuparr_jobs |
5 | List, inspect, trigger, start, schedule jobs |
Example: cleanuparr_jobs(operation="cleanuparr_trigger_job", arguments={"job_type": "QueueCleaner"}).Endpoint-level naming (cleanuparr_<verb>_<resource>) is preserved as theoperation value, so the full endpoint list is still discoverable from eachgroup tool's description at runtime.
Destructive operations are noted in their operation-line doc. Cleanuparrreturns 503 when its configuration database is busy; this server does notretry and instead returns the upstream error to the MCP client.
Request bodies are pass-through JSON dictionaries matching the DTOs in therunning Cleanuparr version. Sensitive update fields should use Cleanuparr'splaceholder 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 bydefault.
