mcp-server-rabbitmq

A Model Context Protocol (MCP) server for RabbitMQ broker management and operations. It lets AI agents manage RabbitMQ brokers conversationally: multi-broker connections, blue-green migration, health checks, and full observability.

Package: amq-mcp-server-rabbitmq on PyPI · Stack: Python, FastMCP, uv

Features

• 31 tools in v4 (enum-based dispatchers), or 61 tools in v3 (one tool per operation) for broker management - connections, queues, exchanges, health checks, observability, and blue-green migration
• 16 composable skills - topology visualization, dead letter analysis, capacity planning, and more
• Multi-broker support - connect multiple brokers simultaneously, switch between them by alias
• Mutative tools gated behind --allow-mutative-tools flag (off by default for safety)
• Tool groups - load only the tools you need with --tool-groups
• Security hardened - SSRF protection, credential stripping, TLS warnings, JWKS HTTPS enforcement

Versions

The server ships two tool layouts so you can choose your upgrade path:

Both are published from this repo. v4 defaults to v3 behavior unless you pass --v4, so installing the latest package never breaks an existing setup on its own. See v4 Mode for the full mapping and the CHANGELOG for the v3 → v4 tool-name table.

Quick Start

Install via PyPI

pip install amq-mcp-server-rabbitmq
# or
uv pip install amq-mcp-server-rabbitmq

Configure in Claude Desktop (v4 mode - recommended)

{
  "mcpServers": {
    "rabbitmq": {
      "command": "uvx",
      "args": [
        "amq-mcp-server-rabbitmq@latest",
        "--v4",
        "--allow-mutative-tools"
      ]
    }
  }
}

Configure in Claude Desktop (v3 mode - legacy, 61 tools)

{
  "mcpServers": {
    "rabbitmq": {
      "command": "uvx",
      "args": [
        "amq-mcp-server-rabbitmq@latest",
        "--allow-mutative-tools"
      ]
    }
  }
}

Basic Usage

Once configured, the agent can connect to your broker and manage it conversationally:

You: Connect to my RabbitMQ broker at rabbitmq.example.com with user admin
You: List all queues and show me which ones have messages backing up
You: Create a dead letter exchange and bind it to the orders queue

v4 Mode

v4 consolidates the 61 individual v3 tools into 31 enum-based dispatchers (29 consolidated groups plus the 2 standalone mutative tools below), reducing context window pressure while preserving full functionality. Each consolidated tool accepts an action parameter to select the operation.

Why opt in to v4

• Fewer tokens. Every tool's name and description is sent to the model on every request, whether or not it's used. v4 roughly halves the tool count (61 → 31) and cuts that idle tool-description text by about 60% - from ~2,300 tokens to ~900 tokens (name + docstrings). That is context budget returned to the actual conversation on every single turn, and a smaller tool list also makes the model faster and more accurate at picking the right tool.
• Faster startup. Fewer tools means less to register and advertise during the MCP handshake, so the server connects and the client finishes tool discovery sooner. With --tool-groups you can trim further - e.g. load only read/health for a monitoring agent - registering just the tools that session needs.

Numbers above are measured against this repo's tool definitions; exact token counts vary by client and model tokenizer.

Key Differences from v3

Standalone Mutative Tools

Two tools remain standalone because they are high-impact operations that benefit from explicit invocation and additional confirmation:

• close_connection - Close a specific connection by name
• rebalance_queues - Rebalance queue leaders across cluster nodes

These require the mutative tool group to be loaded.

Configuration

CLI Arguments

Tool Groups (v4)

Environment Variables

Tools (v3 layout)

The following table shows the v3 tool names. In v4 mode, these are consolidated into 31 enum-based dispatchers (see the v4 Mode section above). Use --v1-compat to register these names alongside v4 tools.

Connection and Session (6 tools)

Read-Only: Queues and Exchanges (7 tools)

Read-Only: Connections and Consumers (4 tools)

Read-Only: Cluster and Nodes (2 tools)

Read-Only: Policies and Shovels (4 tools)

Read-Only: Permissions and Identity (2 tools)

Read-Only: Definitions and Migration (3 tools)

Read-Only: Observability (3 tools)

Health Checks (8 tools)

Mutative: CRUD (16 tools)

Mutative: Migration (4 tools)

Mutative: AMQP (2 tools)

Skills

Skills are composable workflows accessed via rabbitmq_broker_get_skill. They guide the agent through multi-step operations by orchestrating existing tools - no additional code required.

Documentation

In-depth guides live in docs/:

• Multi-Broker — register and switch between brokers by alias
• Authentication — broker auth (SIMPLE/OAuth) and HTTP JWT/JWKS Bearer auth
• Skills — the 16 composable workflow recipes
• Migration — blue-green migration, definition transforms, federation draining
• CHANGELOG — version history and the full v3 → v4 tool-name mapping

Development

Prerequisites

• Python 3.10+
• uv package manager

Running Locally

git clone https://github.com/amazon-mq/mcp-server-rabbitmq.git
cd mcp-server-rabbitmq
uv run amq-mcp-server-rabbitmq

Testing

uv run pytest

Linting

uv run ruff check . && uv run ruff format .

Docker (Local RabbitMQ)

docker-compose up

This starts RabbitMQ 4 with the management plugin on localhost:5672 (AMQP) and localhost:15672 (Management UI). Default credentials: guest / guest.

Security

• Mutative tools disabled by default - pass --allow-mutative-tools to opt in
• Mutative action gating - high-impact operations (close_connection, rebalance_queues, set_permissions) require the mutative tool group to be loaded
• TLS by default - connections use use_tls=True and port 5671 unless overridden
• TLS warnings - non-TLS connections emit a warning in the response so agents can inform users
• SSRF protection - hostname validation blocks connections to private/reserved IP ranges and localhost
• Credential stripping - definition exports automatically strip passwords and sensitive keys before returning to the agent
• URL encoding - all user-supplied names (queues, exchanges, vhosts) are URL-encoded before API calls to prevent injection
• JWKS HTTPS enforcement - the --http-auth-jwks-uri flag rejects non-HTTPS URIs to prevent token validation bypass
• OAuth support - connect with access tokens instead of username/password
• HTTP transport with JWKS auth - run as a remote server with Bearer token validation via configurable IdP

License

Apache-2.0 - see LICENSE for details.