warren-mcp

RabbitMQ tools for Claude — inspect queues, peek at messages, and publish test payloads without leaving your conversation.

warren-mcp is a Model Context Protocol server that exposes RabbitMQ operations as tools for AI assistants. The primary use case is integration testing: Claude can publish a message to any exchange, immediately peek at the target queues, and confirm the message landed where it should — all in a single conversation.

Tools

Read tools

| Tool | What it does | |------|-------------| | list_queues | Discover queues across all vhosts with optional name filter and count limit | | get_queue_stats | Curated stats for a single queue — ready/unacked/total counts, consumers, state, type | | peek_messages | Inspect up to 100 messages non-destructively; bodies are opt-in and prompt-injection-safe | | consume_messages | Pull messages with explicit ack/nack/reject semantics |

Write tools

| Tool | What it does | |------|-------------| | publish_message | Publish to any exchange with the full AMQP properties surface and publisher confirms |

All tools are annotated with readOnlyHint/destructiveHint/idempotentHint so Claude understands their safety profile before calling them.

Quick start

Prerequisites

• Node.js ≥ 18
• A running RabbitMQ instance with the Management Plugin enabled (port 15672)

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "rabbitmq": {
      "command": "npx",
      "args": ["-y", "@majesnix/warren-mcp"],
      "env": {
        "RABBITMQ_HOST": "localhost",
        "RABBITMQ_USER": "guest",
        "RABBITMQ_PASSWORD": "guest"
      }
    }
  }
}

Claude Desktop will start the server automatically and you'll see the RabbitMQ tools in the tool list.

Run directly

RABBITMQ_HOST=localhost \
RABBITMQ_USER=guest \
RABBITMQ_PASSWORD=guest \
npx -y @majesnix/warren-mcp

Environment variables

AMQP connection

| Variable | Default | Required | Description | |----------|---------|----------|-------------| | RABBITMQ_HOST | — | Yes | RabbitMQ broker hostname | | RABBITMQ_PORT | 5672 | No | AMQP port | | RABBITMQ_USER | — | Yes | AMQP username | | RABBITMQ_PASSWORD | — | Yes | AMQP password | | RABBITMQ_VHOST | / | No | Default virtual host |

Management API

| Variable | Default | Required | Description | |----------|---------|----------|-------------| | RABBITMQ_MGMT_HOST | RABBITMQ_HOST | No | Management API hostname (if different from broker) | | RABBITMQ_MGMT_PORT | 15672 | No | Management API port | | RABBITMQ_MGMT_USER | RABBITMQ_USER | No | Management API username | | RABBITMQ_MGMT_PASS | RABBITMQ_PASSWORD | No | Management API password |

The AMQP and management credentials are kept separate so you can connect through an AMQP proxy while still reaching the Management API directly.

Security

Safe by default. This server is designed for integration testing, not production broker management:

• No destructive tools. There are no create/delete/purge operations in v1. Queue and exchange management is intentionally out of scope.
• Credentials never logged. Passwords are redacted in all stderr output and never appear on stdout.
• Prompt injection protection. Message bodies returned by peek_messages and consume_messages are wrapped in explicit untrusted-data framing (<rabbitmq_message_body trust="untrusted">…</rabbitmq_message_body>) so Claude knows not to treat message content as instructions.
• Metadata-only by default. peek_messages returns only message metadata (properties, headers, routing key) unless you explicitly pass includeBody: true.
• Non-destructive peek. peek_messages uses the Management API's ack_requeue_true mode — messages are read and immediately put back. The redelivered flag is never corrupted.

TLS / amqps

To use TLS, set RABBITMQ_PORT=5671 and prefix the host with amqps://, or configure your broker connection string accordingly. The server passes the connection URL directly to amqplib, which supports the full amqps:// scheme including custom CA certificates via NODE_EXTRA_CA_CERTS.

Troubleshooting

Claude doesn't see the tools

Check that warren-mcp started successfully by inspecting Claude Desktop's MCP server logs. The server logs to stderr — look for [warren-mcp] Server running on stdio. If you see a Zod validation error, a required env var is missing.

peek_messages returns an error but the queue exists

The Management Plugin must be enabled. Verify it's running at http://<host>:15672. If RABBITMQ_MGMT_HOST/RABBITMQ_MGMT_PORT differ from your AMQP host, set them explicitly.

Connection refused on first tool call

The AMQP connection is established lazily on the first tool call that needs it. If the broker is unreachable, you'll get a structured error response with a recovery hint — the server itself stays running so you can retry after starting the broker.

Messages not appearing after publish

Check the routing key and exchange binding. Use list_queues to confirm the target queue exists, then peek_messages to verify messages arrived.

Development

git clone https://github.com/majesnix/warren-mcp
cd warren-mcp
npm install

# Build
npm run build

# Type-check only (no emit)
npm run typecheck

# Unit tests (no broker required)
npm test

# Integration tests (requires Docker — starts RabbitMQ via testcontainers)
npm run test:integration

Project structure

src/
  index.ts          Entry point — MCP server, stdio transport, graceful shutdown
  config.ts         Zod env schema, loadConfig(), redactConfig()
  connection.ts     Lazy AMQP connection, withChannel() lifecycle abstraction
  mgmt.ts           Management API URL builder (vhost + queue URL encoding)
  errors.ts         toToolResult(), MgmtHttpError, structured error shapes
  annotations.ts    MCP tool annotation constants
  tools/
    list-queues.ts
    get-queue-stats.ts
    peek-messages.ts
    consume-messages.ts
    publish-message.ts

License

MIT