artemis-mcp-server

An MCP server that lets an AI agent work with an ActiveMQ Artemis broker. Messaging runs over AMQP 1.0; queue management, monitoring and administration run over the broker's Jolokia REST endpoint.

The server is read-only by default. Tools that change broker state are only exposed when ARTEMIS_MODE=admin, and the four destructive operations additionally require an explicit confirm: true argument so an agent cannot delete data by accident.

Requirements

• Node.js 20 or newer
• An Artemis broker with an AMQP acceptor and the web console (Jolokia) enabled

Compatibility

The server uses AMQP 1.0 and the Jolokia REST API rather than a build-specific client, so it is not pinned to one broker release. CI runs the integration suite against these ActiveMQ Artemis versions:

Server	Tested Artemis versions
0.1.x	2.30 – 2.44, and the latest

The server's version is independent of the broker's; there is no need to keep them in step. Older brokers may still work — management calls fall back to legacy Jolokia forms where the API changed — but are unverified, and the server logs a warning at startup when the broker predates the tested range.

Install

Run it directly from a client without installing:

npx artemis-mcp-server

Or install it globally:

npm install -g artemis-mcp-server

Configuration

Configuration comes entirely from environment variables. Missing or invalid values fail fast at startup with a description of what is wrong.

Variable	Required	Default	Description
ARTEMIS_AMQP_URL	yes	—	AMQP endpoint, amqp://host:5672 or amqps://host:5671
ARTEMIS_JOLOKIA_URL	yes	—	Jolokia endpoint, e.g. http://host:8161/console/jolokia
ARTEMIS_USER	yes	—	Broker user for both AMQP and Jolokia
ARTEMIS_PASSWORD	yes	—	Broker password
ARTEMIS_BROKER_NAME	no	0.0.0.0	Broker name used in the management ObjectName
ARTEMIS_MODE	no	read-only	read-only or admin
ARTEMIS_MAX_BROWSE	no	200	Hard cap on messages returned by browse_messages/consume_message
ARTEMIS_JOLOKIA_TIMEOUT_MS	no	10000	Jolokia request timeout
ARTEMIS_AMQP_TIMEOUT_MS	no	15000	AMQP connection and operation timeout
ARTEMIS_LOG_LEVEL	no	info	error, warn, info or debug

See .env.example for a starting point. The password is never written to the logs.

Using it with an MCP client

Claude Code (plugin)

This repository is a Claude Code plugin marketplace. Add it and install the plugin; Claude Code prompts for the broker URL, credentials and mode, then runs the server for you:

/plugin marketplace add k-krawczyk/artemis-mcp-server
/plugin install artemis-mcp-server@artemis-mcp

The password is stored in your system keychain.

Claude Code (CLI)

Without the plugin, register the server directly:

claude mcp add artemis \
  --env ARTEMIS_AMQP_URL=amqp://localhost:5672 \
  --env ARTEMIS_JOLOKIA_URL=http://localhost:8161/console/jolokia \
  --env ARTEMIS_USER=artemis \
  --env ARTEMIS_PASSWORD=artemis \
  --env ARTEMIS_MODE=admin \
  -- npx -y artemis-mcp-server

Codex

In ~/.codex/config.toml:

[mcp_servers.artemis]
command = "npx"
args = ["-y", "artemis-mcp-server"]
env = { ARTEMIS_AMQP_URL = "amqp://localhost:5672", ARTEMIS_JOLOKIA_URL = "http://localhost:8161/console/jolokia", ARTEMIS_USER = "artemis", ARTEMIS_PASSWORD = "artemis", ARTEMIS_MODE = "admin" }

Cursor

In .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "artemis": {
      "command": "npx",
      "args": ["-y", "artemis-mcp-server"],
      "env": {
        "ARTEMIS_AMQP_URL": "amqp://localhost:5672",
        "ARTEMIS_JOLOKIA_URL": "http://localhost:8161/console/jolokia",
        "ARTEMIS_USER": "artemis",
        "ARTEMIS_PASSWORD": "artemis",
        "ARTEMIS_MODE": "admin"
      }
    }
  }
}

VS Code

In .vscode/mcp.json (note the servers key):

{
  "servers": {
    "artemis": {
      "command": "npx",
      "args": ["-y", "artemis-mcp-server"],
      "env": {
        "ARTEMIS_AMQP_URL": "amqp://localhost:5672",
        "ARTEMIS_JOLOKIA_URL": "http://localhost:8161/console/jolokia",
        "ARTEMIS_USER": "artemis",
        "ARTEMIS_PASSWORD": "artemis",
        "ARTEMIS_MODE": "admin"
      }
    }
  }
}

Claude Desktop and other clients

Most clients accept the same mcpServers shape as Cursor above. Add the artemis entry to the client's MCP config file (for Claude Desktop, claude_desktop_config.json).

Tools

Tools marked write are hidden unless ARTEMIS_MODE=admin. Tools marked confirm do nothing unless called with confirm: true.

Messaging

• send_message (write) — send one message to an address or queue. Arguments: address, body, bodyType (text or bytes, base64 for bytes), subject?, durable?, ttlMs?, messageId?, properties?.

  { "address": "orders", "body": "hello", "properties": { "priority": 9 } }

• browse_messages — read messages without removing them. Arguments: queue, address?, limit?.
• consume_message (write) — receive and remove messages. Arguments: queue, address?, count?.

For a named queue on a multicast address, pass both queue and address; the server addresses it as address::queue.

Management

• list_queues — names of all queues.
• list_addresses — names of all addresses.
• create_queue (write) — create a queue. Arguments: name, address?, routingType? (anycast/multicast), durable?, filter?, maxConsumers?, autoCreateAddress?.
• delete_queue (write, confirm) — destroy a queue. Arguments: name, removeConsumers?, autoDeleteAddress?, confirm.
• get_queue_info — configuration of a queue (address, routing type, durability, filter).

Monitoring

• get_queue_stats — runtime counters (message count, added, acknowledged, delivering, scheduled, consumers).
• get_broker_overview — version, uptime, memory usage, connection/consumer totals and queue/address counts.
• list_consumers — consumers currently attached.
• list_connections — open connections.

Administration

• purge_queue (write, confirm) — remove every message from a queue.

  { "queue": "orders", "confirm": true }

• move_messages (write, confirm) — move messages to another queue. Arguments: queue, targetQueue, filter?, confirm.
• delete_messages (write, confirm) — remove messages matching a filter. A filter is required so this cannot become an accidental purge.
• retry_dlq (write, confirm) — resend a dead-letter queue's messages to their original destination.

Security

• The default mode is read-only. Granting write access is an explicit choice through ARTEMIS_MODE=admin.
• Destructive operations require confirm: true on every call.
• Credentials are redacted from log output and stack traces are never returned to the client; unexpected failures surface as a generic message and are logged on stderr.
• Jolokia is an administrative surface. In production use a dedicated service account with the least privilege it needs, keep the endpoint off the public network, and prefer TLS for both AMQP and the console.

Development

Start a local broker with the console and Jolokia enabled:

docker compose up -d

Then:

npm install
npm run build
npm test                 # unit tests
npm run test:integration # spins up a broker with Testcontainers; needs Docker

npm run lint, npm run typecheck and npm run format:check round out the checks that CI runs on every push and pull request.

License

MIT