Provides read-only tools for debugging a running Celery deployment, including listing workers and their pool/concurrency/uptime/prefetch/task stats, checking queue depths, and identifying which workers consume each queue. Supports diagnosing stuck tasks and routing/consumer issues.
Allows inspection of RabbitMQ queues used by Celery, reporting queue existence, message backlog, consumer counts, and which workers consume each queue using passive declares without creating queues.
Allows inspection of Redis-backed Celery queues, reporting message depths and worker consumption. Redis has no native consumer concept, so consumer counts are unavailable and worker consumption is derived from Celery workers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-server-celery why are my email tasks not running?"
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.
An MCP server that lets AI agents debug a running Celery deployment. It checks which workers are alive, what each one consumes, and where messages are piling up — the checks you'd otherwise run by hand with celery inspect and rabbitmqctl every time something gets stuck.
It is read-only by default. Broker passwords are masked in every response, including the broker info that Celery's own inspect stats sends back in plain text.
Works with RabbitMQ (amqp://) and Redis (redis://, rediss://).
Tool | What it answers |
| Which workers respond, their pool and concurrency, uptime, prefetch count, tasks processed, and the queues each one listens to. |
| How many messages are waiting in each queue and which workers consume it. With no arguments it checks your configured queues plus every queue a live worker consumes. |
Coming next: active_tasks, reserved_tasks, scheduled_tasks, task_status, and diagnose_stuck, which cross-references the above to flag queues no worker listens to, tasks routed to queues with no consumer, and workers that stopped responding. See the roadmap.
Related MCP server: Kalymos Hoag
Requires Python 3.10+ and uv.
uvx mcp-server-celeryUntil the first PyPI release, run it from GitHub:
uvx --from git+https://github.com/taltal-beep/mcp-server-celery mcp-server-celeryAll configuration is through environment variables.
Variable | Default | Purpose |
|
| Broker to inspect. |
| — | Result backend (used by |
| — | Import path of your app, e.g. |
|
| Seconds to wait for worker replies. Raise it for large or slow clusters. |
CELERY_APP has to be importable, so run the server from your project's directory and environment:
uv run --with mcp-server-celery mcp-server-celeryclaude mcp add celery -e CELERY_BROKER_URL=redis://localhost:6379/0 -- uvx mcp-server-celeryIn .cursor/mcp.json:
{
"mcpServers": {
"celery": {
"command": "uvx",
"args": ["mcp-server-celery"],
"env": { "CELERY_BROKER_URL": "redis://localhost:6379/0" }
}
}
}In claude_desktop_config.json, use the same command, args and env block as Cursor, under mcpServers.
Ask the agent "why are my email tasks not running?" and it can call queue_depths:
{
"broker": "amqp://app:****@rabbit:5672//",
"queues": [
{ "queue": "celery", "exists": true, "messages": 0, "consumers": 2, "workers_consuming": ["w1@web", "w2@web"] },
{ "queue": "emails", "exists": true, "messages": 1843, "consumers": 0, "workers_consuming": [] }
]
}emails has a backlog and no worker consumes it: the workers were started without -Q emails.
Redis has no notion of consumers, so consumers is null; use workers_consuming, which comes from the workers themselves. Redis also deletes a queue's key once it is empty, so a drained queue shows "messages": 0, "exists": null.
RabbitMQ checks use a passive declare, so the server never creates a queue. A queue that doesn't exist shows "exists": false.
Workers that are too busy to answer within CELERY_INSPECT_TIMEOUT don't appear in list_workers. If a worker you expect is missing, try a larger timeout argument before assuming it's dead.
Every tool is annotated readOnlyHint: true. Write actions (revoke, retry, purge) will only be available behind an explicit opt-in flag.
URL credentials and password/secret/token fields are masked in all output and error messages.
v0.1 — list_workers, queue_depths ✅
v1 — active_tasks, reserved_tasks, scheduled_tasks, task_status(task_id), diagnose_stuck
v2 — summarize_failures: groups recent failures by task name and exception type. Celery keeps no failure history by default, so this needs an event listener.
uv sync
uv run pytest tests/unit
uv run ruff check . && uv run ruff format --check .Integration tests start a real worker and need a broker:
CELERY_BROKER_URL=redis://localhost:6379/0 uv run pytest tests/integration -m integrationCI runs them against Redis and RabbitMQ on every push.
MIT
List workers that reply to broadcast, with pool, concurrency, uptime and the queues each consumes.
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | Seconds to wait for worker replies. Defaults to CELERY_INSPECT_TIMEOUT. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope context ('workers that reply to broadcast'), which hints that unreachable workers may be omitted, but it never states that this is a live broadcast whose results are timing-dependent or that non-responding workers are silently dropped.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tightly packed sentence with no filler, front-loading the action and scope before the field list. Nothing needs trimming.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation here, and annotations cover the safety profile. The one remaining gap is the live-broadcast/timing behavior of the inspection, which an agent would benefit from knowing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single timeout parameter and its CELERY_INSPECT_TIMEOUT default are fully documented in the schema. The description adds nothing about the parameter, which is acceptable at baseline 3 when the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List workers') plus a scope qualifier ('that reply to broadcast') and enumerates the returned fields (pool, concurrency, uptime, queues consumed). An agent can distinguish this from the queue_depths sibling without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement of when to use this versus queue_depths or any other inspection tool, and no prerequisites or exclusions. Usage is only implicitly inferable from the name and the field list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count waiting messages per queue and show which workers consume each one. Works on RabbitMQ and Redis.
| Name | Required | Description | Default |
|---|---|---|---|
| queues | No | Queue names to check. Defaults to configured queues plus every queue a worker consumes. | |
| timeout | No | Seconds to wait for worker replies. Defaults to CELERY_INSPECT_TIMEOUT. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it counts 'waiting' messages and supports RabbitMQ and Redis, but does not disclose authentication needs, rate limits, or other operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover the safety profile, the description is largely complete for a read-only inspection tool. It only misses guidance on how it relates to list_workers, which would help tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the two optional parameters. The description adds no parameter-level details, which is the baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Count waiting messages per queue and show which workers consume each one.' This clearly distinguishes it from a generic worker listing, but it does not explicitly differentiate itself from the sibling tool list_workers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_workers. It only notes technology support ('Works on RabbitMQ and Redis'), which is context rather than usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0list_workersqueue_depthsScored across 2 tools
The two tools target distinct resources: list_workers is worker-centric while queue_depths is queue-centric. There is minor overlap since both surface the worker-to-queue consumption mapping, but the primary purpose of each is clear.
Both names are snake_case, which is consistent. However list_workers follows a verb_noun pattern while queue_depths is noun_noun, a minor deviation in convention.
Two tools is thin for a Celery monitoring server, which typically covers tasks, queues, and workers. It is not extreme, but the surface feels under-scoped for the domain.
Celery monitoring spans workers, queues, and tasks, but only worker and queue visibility is offered. Task inspection (list tasks, task status, revoke) and queue management (purge) are notably absent, leaving significant gaps.
Debug background jobs — runs, traces, spans, schedules, queues and deployments.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Connect, monitor, and control AI agents — tasks, approvals, schedules, and governance.
Data + AI observability — monitor and troubleshoot production-grade agents and the context they use.
