Add romarr-mcp: curated MCP server for ROMarr (21 tools) #21

2026-11-04T22:25:12+01:00

hermes-agent commented

2026-11-04 22:25:12 +01:00

ROMarr has no MCP server, and it ships a generated OpenAPI 3.1 spec (133 operations) with no tags — so the generic spec-to-MCP bridge (awslabs/openapi-mcp-server) exposes all 133 with machine names like postApiV1AuditQuarantineMove. I verified that bridge works (133 tools, live call OK) and then wrote this instead: 21 named tools with typed arguments.

Stdlib only (urllib, json, ssl) so the derivation vendors no wheels and needs no MCP SDK — the protocol surface here is initialize / tools/list / tools/call / ping.

Tools (14 read, 7 write):

system_status, system_counts, tasks, platforms
library, wanted_missing, queue, history, manual_scan
search_releases, grab_release (interactive search → grab by id)
audit (DAT state), audit_run, duplicates, quarantine_duplicates
rename_preview, indexers, download_clients, request_game, import_finished

Env: ROMARR_URL (default http://127.0.0.1:6868), ROMARR_API_KEY (required), ROMARR_READ_ONLY (refuses every write), ROMARR_TIMEOUT, ROMARR_VERIFY_TLS=0.

Verified against a live ROMarr 1.8.0 (throwaway instance, ROMARR_API_KEY=testkey):

built store binary, initialize OK, tools/list → 21 tools with readOnlyHint/destructiveHint annotations
all 21 tools called: 0 transport/protocol errors; every response is real ROMarr JSON (system_counts → {"games":0,…}, platforms → 39 platforms, audit_run → {"status":"running"})
ROMARR_READ_ONLY=1 refuses all 7 write tools with a clear error
no key → error: ROMARR_API_KEY is not set… instead of a traceback

Destructive tools need an explicit confirm=true (quarantine_duplicates). queue_action is marked destructiveHint.

Gateway wiring (backend + scope + lock bump) comes in a follow-up config PR once this is merged, since the lock must point at the merged rev.

ROMarr has no MCP server, and it ships a generated OpenAPI 3.1 spec (133 operations) with no tags — so the generic spec-to-MCP bridge (`awslabs/openapi-mcp-server`) exposes all 133 with machine names like `postApiV1AuditQuarantineMove`. I verified that bridge works (133 tools, live call OK) and then wrote this instead: 21 named tools with typed arguments. Stdlib only (`urllib`, `json`, `ssl`) so the derivation vendors no wheels and needs no MCP SDK — the protocol surface here is initialize / tools/list / tools/call / ping. Tools (14 read, 7 write): - `system_status`, `system_counts`, `tasks`, `platforms` - `library`, `wanted_missing`, `queue`, `history`, `manual_scan` - `search_releases`, `grab_release` (interactive search → grab by id) - `audit` (DAT state), `audit_run`, `duplicates`, `quarantine_duplicates` - `rename_preview`, `indexers`, `download_clients`, `request_game`, `import_finished` Env: `ROMARR_URL` (default `http://127.0.0.1:6868`), `ROMARR_API_KEY` (required), `ROMARR_READ_ONLY` (refuses every write), `ROMARR_TIMEOUT`, `ROMARR_VERIFY_TLS=0`. Verified against a live ROMarr 1.8.0 (throwaway instance, `ROMARR_API_KEY=testkey`): - built store binary, `initialize` OK, `tools/list` → 21 tools with `readOnlyHint`/`destructiveHint` annotations - all 21 tools called: 0 transport/protocol errors; every response is real ROMarr JSON (`system_counts` → `{"games":0,…}`, `platforms` → 39 platforms, `audit_run` → `{"status":"running"}`) - `ROMARR_READ_ONLY=1` refuses all 7 write tools with a clear error - no key → `error: ROMARR_API_KEY is not set…` instead of a traceback Destructive tools need an explicit `confirm=true` (`quarantine_duplicates`). `queue_action` is marked `destructiveHint`. Gateway wiring (backend + scope + lock bump) comes in a follow-up config PR once this is merged, since the lock must point at the merged rev.

hermes-agent added 1 commit 2026-11-04 22:25:13 +01:00

Add romarr-mcp: curated MCP server for ROMarr

NixOS Configuration CI / Nix Flake Check (pull_request) Successful in 19s

Details

c57cf38abe

luis merged commit 2393f594b3 into main

2026-11-04 22:30:02 +01:00

luis deleted branch feat/romarr-mcp

2026-11-04 22:30:04 +01:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: luis/mcp-servers#21