What can you do with this server?

This server exposes Cleanuparr's REST API as MCP tools for inspecting, configuring, and managing Cleanuparr. * Health & Status: Check liveness/readiness, detailed health reports, version/uptime/resource status, download client and *arr (Sonarr/Radarr/Lidarr) connection statuses, and run health checks. * Jobs: List scheduled jobs, get job details, trigger manual one-time runs, start jobs with custom schedules, and update job schedules. * Events & Strikes: List/filter/retrieve events, timelines, types, and severities; manage manual events (resolve one/all, statistics); list/filter/delete strikes and purge all strikes. * Statistics: View aggregate v2 stats, timeline metrics (events, strikes, recovered, removed, malware blocked), Seeker search summaries/events, and custom-format score data, upgrades, instances, and history. * Configuration: Read/update general settings (dry-run, auth, retry/timeout, retention, logging, etc.); manage *arr instances and download clients (create/update/delete/test); configure queue cleaner, download cleaner, dead torrent, unlinked/orphaned file handling, and seeding rules (including reorder). * Feature Configurations: Manage malware blocker, Seeker, and blacklist synchronizer settings. * Notifications: List, create, update, test, and delete notification providers (Notifiarr, Apprise, ntfy, Telegram, Discord, Pushover, Gotify); check Apprise CLI availability. * Destructive Actions: Purge strikes, resolve all manual events, and perform clearly marked destructive updates.

How do I use cleanuparr-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cleanuparr-mcp show me recent cleanup history and stats" 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.

cleanuparr-mcp

by arr-mcps

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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

Related MCP server: job-search-mcp

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 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.

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 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.

Available Tools

8 tools

cleanuparr_arr_download_clientsA

cleanuparr arr download clients operations on Cleanuparr. Pass operation and an arguments dict matching that operation's parameters.

cleanuparr_create_arr_instance(arr_type, instance) — Create an *arr instance. DTO fields: enabled, name, url, apiKey, version, externalUrl.
cleanuparr_create_download_client(client) — Create a download client. DTO includes enabled, name, typeName, type, host, username, password, urlBase, externalUrl, and directory source/target.
cleanuparr_delete_arr_instance(arr_type, instance_id) — Delete an *arr instance by GUID.
cleanuparr_delete_download_client(client_id) — Delete a download client by GUID.
cleanuparr_get_arr_config(arr_type) —
cleanuparr_get_general_config() — Get general configuration, including dry-run and auth settings.
cleanuparr_list_arr_instances(arr_type) —
cleanuparr_list_download_clients() — List configured download clients.
cleanuparr_purge_strikes() — Purge all stored strikes. This is irreversible.
cleanuparr_test_arr_instance(arr_type, instance) — Test an *arr connection. DTO fields: url, apiKey, version, optional instanceId.
cleanuparr_test_download_client(client) — Test a download client. DTO includes typeName, type, host, credentials, urlBase, and optional clientId.
cleanuparr_update_arr_config(arr_type, config) — Replace one *arr config, normally containing failedImportMaxStrikes.
cleanuparr_update_arr_instance(arr_type, instance_id, instance) — Replace an *arr instance. Use Cleanuparr's secret placeholder for apiKey.
cleanuparr_update_download_client(client_id, client) — Replace a download client. Use the secret placeholder for password.
cleanuparr_update_general_config(config) — Merge fields into the current general config and PUT the result. A raw PUT replaces the whole resource, so sending only changed fields (e.g. {"dryRun": false}) resets every unspecified field — including displaySupportBanner and the auth object — to defaults. This read-modify-write preserves current values for anything not in config. Fields include dryRun, retry/timeout settings, ignoredDownloads, connectivity, retention, log, and auth objects.