mcp-server-rabbitmq

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

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

Versions

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

Version	Layout	Upgrade impact	Choose it when
v3 (3.x)	61 tools, one per operation (e.g. rabbitmq_broker_list_queues). All v2.x tool names preserved.	Non-breaking - a drop-in upgrade from v2.x.	You have existing prompts/integrations bound to v2/v3 tool names and want zero churn.
v4 (4.x)	31 enum-based dispatchers (e.g. queues(action="list")), selectable via --tool-groups.	Breaking - tool names change (opt in with --v4). --v1-compat re-registers v3 aliases to ease migration.	You want ~60% fewer tool-description tokens per turn, faster startup, and per-group tool loading (see Why opt in to v4).

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

Aspect	v3	v4
Tool count	61	31 (29 dispatchers + 2 standalone mutative)
Naming	rabbitmq_broker_list_queues	queues(action="list")
Loading	All or nothing	Selectable via --tool-groups
Compat	N/A	--v1-compat registers v3 aliases

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

Argument	Description
--v4	Enable v4 consolidated tool mode (31 tools instead of 61)
--tool-groups	Select which tool groups to load (space-separated). Options: core, read, mutative, migration, observability, health
--v1-compat	Register v3 tool name aliases alongside v4 tools (for migration)
--allow-mutative-tools	Enable tools that can create, modify, or delete resources (default: off)
--management-port	RabbitMQ Management API port (default: 443 for TLS, 15672 for non-TLS)
--http	Use Streamable HTTP transport instead of stdio
--server-port	Port to run the MCP server on (default: 8888)
--http-auth-jwks-uri	JWKS URI for JWKS bearer token verification
--http-auth-issuer	Expected token issuer (iss) to enforce
--http-auth-audience	Expected token audience (aud) to enforce
--http-auth-required-scopes	Required token scopes to enforce

Tool Groups (v4)

Group	Tools	Gate
core	connect, connect_oauth, broker, get_skill, get_guideline	Always loaded
read	queues, exchanges, connections, cluster, entities, overview, policies, shovels, auth	Always loaded
mutative	manage_queue, manage_exchange, manage_binding, manage_policy, manage_vhost, publish, close_connection, rebalance_queues	Requires --allow-mutative-tools
migration	definitions_export, definitions_import, definitions_compare, definitions_migrate, migration_readiness, federation_setup	Requires --allow-mutative-tools
observability	find_queues	Always loaded
health	health	Always loaded

Environment Variables

Variable	Description
FASTMCP_LOG_LEVEL	Log level: DEBUG, INFO, WARNING (default), ERROR
RABBITMQ_AMQP_ENDPOINT	Connect at startup, e.g. amqps://user:pass@host:5671. See below.
RABBITMQ_MANAGEMENT_ENDPOINT	Management API endpoint, e.g. https://user:pass@host:443. See below.
RABBITMQ_ALIAS	Alias for the environment-configured broker (default: its hostname)

Connecting at startup

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.

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)

Tool	Description
rabbitmq_broker_initialize_connection	Connect to a broker with username/password (SIMPLE auth)
rabbitmq_broker_initialize_connection_with_oauth	Connect to a broker using an OAuth token
rabbitmq_broker_select	Switch the active broker by alias
rabbitmq_broker_list_registered_brokers	List all registered broker connections and which is active
rabbitmq_broker_get_guideline	Get best-practice guidelines for RabbitMQ deployment and sizing
rabbitmq_broker_get_skill	Get a composable workflow recipe (see Skills section below)

Read-Only: Queues and Exchanges (7 tools)

Tool	Description
rabbitmq_broker_list_queues	List all queues in the broker
rabbitmq_broker_list_exchanges	List all exchanges in the broker
rabbitmq_broker_list_vhosts	List all virtual hosts
rabbitmq_broker_get_queue_info	Get detailed information about a specific queue
rabbitmq_broker_get_exchange_info	Get detailed information about a specific exchange
rabbitmq_broker_get_bindings	Get bindings, optionally filtered by queue or exchange
rabbitmq_broker_get_messages	Peek at messages in a queue without consuming them

Read-Only: Connections and Consumers (4 tools)

Tool	Description
rabbitmq_broker_list_connections	List all connections on the broker
rabbitmq_broker_list_consumers	List all consumers on the broker
rabbitmq_broker_list_channels	List all open channels on the broker
rabbitmq_broker_list_users	List all users on the broker

Read-Only: Cluster and Nodes (2 tools)

Tool	Description
rabbitmq_broker_get_cluster_nodes_info	Get the list of nodes and their info in the cluster
rabbitmq_broker_get_node_information	Get detailed node info including memory, disk, uptime

Read-Only: Policies and Shovels (4 tools)

Tool	Description
rabbitmq_broker_list_policies	List all policies in a virtual host
rabbitmq_broker_get_policy	Get a specific policy by name
rabbitmq_broker_list_shovels	List all shovels on the broker
rabbitmq_broker_get_shovel_info	Get detailed information about a specific shovel

Read-Only: Permissions and Identity (2 tools)

Tool	Description
rabbitmq_broker_get_permissions	Get permissions for a user in a virtual host
rabbitmq_broker_whoami	Get the current authenticated user

Read-Only: Definitions and Migration (3 tools)

Tool	Description
rabbitmq_broker_get_broker_definition	Get full broker definitions (exchanges, queues, bindings, users, etc.)
rabbitmq_broker_compare_definitions	Compare definitions between two connected brokers
rabbitmq_broker_check_migration_readiness	Pre-flight check for blue-green migration

Read-Only: Observability (3 tools)

Tool	Description
rabbitmq_broker_get_overview	Get cluster-wide stats: version, node count, message rates, object totals
rabbitmq_broker_find_queues_by_threshold	Find queues by criteria: depth, idle time, no consumers, unacked messages
rabbitmq_broker_get_connection_churn	Get connection/channel open and close rates

Health Checks (8 tools)

Tool	Description
rabbitmq_broker_is_in_alarm	Check if the broker is in alarm
rabbitmq_broker_is_quorum_critical	Check if quorum queues have minimum online quorum
rabbitmq_broker_check_local_alarms	Check for local alarms on the active broker
rabbitmq_broker_check_certificate_expiration	Check if TLS certificates expire within a timeframe
rabbitmq_broker_check_protocol_listener	Check if a protocol listener is active
rabbitmq_broker_check_virtual_hosts	Check health of all virtual hosts
rabbitmq_broker_list_feature_flags	List all feature flags and their status
rabbitmq_broker_list_deprecated_features	List deprecated features currently in use

Mutative: CRUD (16 tools)

Tool	Description
rabbitmq_broker_create_queue	Create a queue (quorum, classic, or stream)
rabbitmq_broker_delete_queue	Delete a specific queue
rabbitmq_broker_purge_queue	Remove all messages from a queue
rabbitmq_broker_create_exchange	Create an exchange (direct, fanout, topic, headers)
rabbitmq_broker_delete_exchange	Delete a specific exchange
rabbitmq_broker_create_binding	Create a binding from an exchange to a queue
rabbitmq_broker_delete_binding	Delete a binding
rabbitmq_broker_create_policy	Create or update a policy
rabbitmq_broker_delete_policy	Delete a policy
rabbitmq_broker_create_vhost	Create a virtual host
rabbitmq_broker_delete_vhost	Delete a virtual host and all its resources
rabbitmq_broker_set_permissions	Set permissions for a user in a virtual host
rabbitmq_broker_close_connection	Close a specific connection by name
rabbitmq_broker_update_definition	Update server definitions
rabbitmq_broker_export_definitions	Export definitions with optional transformations
rabbitmq_broker_import_definitions	Import definitions to the active broker

Mutative: Migration (4 tools)

Tool	Description
rabbitmq_broker_migrate_definitions	Export, transform, and import definitions between brokers
rabbitmq_broker_setup_federation	Set up federation upstream and policy for message draining
rabbitmq_broker_rebalance_queues	Rebalance queue leaders across cluster nodes
rabbitmq_broker_publish_message	Publish a message via HTTP Management API (diagnostics)

Mutative: AMQP (2 tools)

Tool	Description
rabbitmq_broker_enqueue	Publish a message to a specific queue via AMQP
rabbitmq_broker_fanout	Publish a message to a fanout exchange via AMQP

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.

Skill	What it does	Tools it composes
pre_flight_migration_check	Check alarms on both brokers + compare definitions for go/no-go	is_in_alarm, compare_definitions
migrate_definitions	Export from source with transforms, import to target	export_definitions, import_definitions
setup_federation	Verify federation plugin, create upstream and policy	get_broker_overview, import_definitions
queue_metrics_analysis	Interpret publish/deliver rates and backlog trends	get_queue_info
node_resource_analysis	Calculate memory %, disk headroom, FD usage per node	get_node_information, get_cluster_nodes_info
export_topology_graph	Generate Mermaid diagram of exchange-binding-queue graph	list_exchanges, list_queues, get_bindings
trace_message_route	Predict which queues receive a message given exchange + routing key	get_exchange_info, get_bindings
find_orphaned_queues	Find queues with no bindings and no consumers	list_queues, get_bindings, list_consumers
find_unbound_exchanges	Find exchanges with no outbound bindings (excluding amq.*)	list_exchanges, get_bindings
trace_dead_letter_chain	Walk x-dead-letter-exchange arguments to map the full DLX chain	get_queue_info, get_bindings
inspect_dead_letters	Peek at DLQ messages and extract x-death headers (source, reason)	get_messages
dlq_summary	Aggregate dead letters by source queue and rejection reason	list_queues, get_queue_info, get_messages
broker_recommendations	Compare live broker state against best-practice guidelines	get_broker_overview, get_cluster_nodes_info, list_queues, get_guideline
queue_health_assessment	Assess queue type, consumers, depth, and policy coverage	get_queue_info, get_guideline
resource_headroom_check	Compute resource utilization % vs watermarks, project time-to-alarm	get_cluster_nodes_info
policy_conflict_detection	Find overlapping policy patterns and report priority winners	list_policies

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.