The Rotor admin MCP server lets a Claude Code session on your laptop inspect and triage a Rotor deployment in natural language. No SSH, no redis-cli.
This is separate from the customer-facing Rotor MCP at rotor.sh/mcp (which uses rt_ws_ / rt_team_ keys). The admin MCP is operator-only and gated by a single ADMIN_TOKEN shared with the API.
Install
- •
Build the server
From the rotor monorepo root:
pnpm --filter=@rotor/mcp-server build - •
Register with Claude Code
claude mcp add rotor-admin -- node $(pwd)/packages/mcp-server/dist/index.js - •
Set environment variables
Add to your shell profile or your Claude Code MCP config:
export ROTOR_ADMIN_TOKEN="<value of ADMIN_TOKEN on the API>" export ROTOR_API_URL="https://api.rotor.sh" # optional override - •
Verify
Open a fresh Claude Code session and ask "What workspaces are running on Rotor?" — Claude should call
rotor_list_workspacesand render the result.
Available tools
| Tool | Destructive | Description |
|---|---|---|
rotor_list_workspaces | — | List all workspaces with plan and creation date |
rotor_get_workspace_queues | — | Queue depth per state for every queue in a workspace |
rotor_get_workspace_schedules | — | Schedules with BullMQ state and drift flag |
rotor_inspect_job | — | Full job detail (data, return value, failure reason) |
rotor_get_dlq | — | DLQ depth and recent failed jobs |
rotor_replay_dlq | yes | Idempotently re-enqueue DLQ jobs (deterministic IDs) |
rotor_fire_schedule_now | yes | Out-of-band schedule execution (does not reset cron) |
Destructive tools require confirm: true in the call arguments. Claude Code will ask you to confirm before invoking them.
Idempotency guarantees
rotor_replay_dlq uses BullMQ's job-id uniqueness to dedup replays. Calling it twice with the same parameters produces the same replay-${originalId} IDs and BullMQ silently no-ops the second addBulk.
rotor_fire_schedule_now enqueues a one-shot job — it does not call upsertJobScheduler. The cron's normal next_run_at is unchanged.
Troubleshooting
See the package README at packages/mcp-server/README.md for env var and 403 troubleshooting.