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, MCP Python SDK (mcp.server.fastmcp), uv

• 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
• Startup connection from the environment - set RABBITMQ_AMQP_ENDPOINT so the tools work without a connect call, for hosts that respawn the server per session
• 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

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.

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

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

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

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 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.

• 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.

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.

Normally the agent calls the connect tool once per session. Some MCP hosts, particularly aggregators and proxies, start a fresh server process per session or per tool call, so that connection state does not survive and later calls fail with "No active broker". Setting an endpoint URI makes the server connect during startup instead, so the tools work on every spawn:

{
  "mcpServers": {
    "rabbitmq": {
      "command": "uvx",
      "args": ["amq-mcp-server-rabbitmq@latest", "--v4"],
      "env": {
        "RABBITMQ_AMQP_ENDPOINT": "amqps://admin:pass@broker.example.com:5671"
      }
    }
  }
}

Details:

• The scheme selects TLS and the default port. amqps is TLS on 5671, amqp is plaintext on 5672, https is TLS on 443, http is plaintext on 15672. An explicit :port overrides the default.
• Either variable is enough. Give only RABBITMQ_AMQP_ENDPOINT and the management endpoint is derived from it (same host and credentials, matching TLS), and vice versa. Set both when they differ, for example when the management API is on another host or uses separate credentials.
• --management-port still applies as the derived management port when RABBITMQ_MANAGEMENT_ENDPOINT is not set.
• Percent-encode reserved characters in credentials. A password of p@ss/word is written p%40ss%2Fword.
• Failures are non-fatal. An unreachable broker or malformed URI logs a warning and leaves the connect tool available, rather than killing the server.
• Works in both v3 and v4 mode. Credentials are never written to logs or error messages. OAuth is not supported through these variables; use the OAuth connect tool.

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.

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.

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

• Python 3.10+
• uv package manager

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

uv run pytest

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

docker-compose up

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

• 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

Apache-2.0 - see LICENSE for details.