mradovic95/activemq-mcp-server

ActiveMQ MCP Server

A Model Context Protocol (MCP) server that provides AI systems with seamless integration to ActiveMQ Classic message brokers using REST API. This server exposes ActiveMQ operations as MCP tools, enabling AI assistants to interact with message queues and topics programmatically.

Features

• Multiple Broker Connections: Manage connections to multiple ActiveMQ brokers simultaneously
• Dynamic Connection Management: Add and remove broker connections at runtime
• Comprehensive Queue Operations: Send, receive, browse, and purge messages
• Topic Support: Publish, subscribe, and list topics with detailed information
• Message Browsing: Browse messages in queues without consuming them for debugging and monitoring
• Destination Discovery: List all queues and topics with their current statistics
• Health Monitoring: Automatic connection health checks and broker status monitoring
• Configuration Management: Load connections from config files with on-demand connection
• Backup and Migration: Export/import connection configurations for environment migration
• MCP Protocol Compliance: Full compatibility with MCP-enabled AI systems
• CLI Interface: Easy command-line management and testing

AI-Powered ActiveMQ Management

With this MCP server, you can ask your AI assistant natural language questions and get instant results:

📊 Monitoring & Discovery

• "Show me all queues and their message counts" → Get comprehensive queue statistics
• "Are there any messages stuck in the error queue?" → Browse messages without consuming them
• "What's the health status of my production broker?" → Real-time broker health check

📨 Message Operations

• "Send a test message to the user.notifications queue" → Message sent with confirmation
• "Check the last 5 messages in the payment.failed queue" → Browse recent messages safely
• "Clear all messages from the staging.test queue" → Purge queue with confirmation
• "Get a message template for the orders.processing queue, then change the body to 'Order #12345 processed' and send it" → Browse existing message format and send customized message

🔗 Connection Management

• "Connect to my production ActiveMQ broker" → Establish connection from config
• "Show me all my configured broker connections" → Display available configurations
• "Test if my development broker is responding" → Connection health verification

📢 Topic Operations

• "Publish an alert to the system.monitoring topic" → Broadcast message to subscribers
• "List all available topics on my broker" → Discover topic destinations
• "Subscribe to user.events and show me new messages" → Real-time topic monitoring
• "Which virtual topics do I have? List all of them and all queues associated with them" → Discover virtual topic patterns and their consumer queues

💾 Backup & Migration

• "Export all my broker connections for backup" → Save connection configurations to file
• "Import connections from my staging environment to production setup" → Migrate broker configurations
• "Backup my current ActiveMQ setup before making changes" → Create configuration snapshot
• "Copy connection settings from development to my local environment" → Clone environment configurations

Architecture & Project Structure

Clean Layered Architecture

The ActiveMQ MCP Server follows clean layered architecture principles with composition patterns:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude/AI     │────│   MCP Protocol  │────│   ActiveMQ MCP  │
│   Assistant     │    │   (JSON-RPC)    │    │     Server      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                       │
                                              ┌────────┴────────┐
                                              │   MCP Handler   │
                                              │   Coordinator   │
                                              └────────┬────────┘
                                                       │
                                              ┌────────┴────────┐
                                              │ Connection      │
                                              │ Manager         │
                                              └────────┬────────┘
                                                       │
                                              ┌────────┴────────┐
                                              │ ActiveMQFacade  │
                                              └────────┬────────┘
                                                       │
                        ┌──────────────────────────────┼──────────────────────────────┐
                        │                              │                              │
                ┌───────┴────────┐            ┌────────┴────────┐            ┌────────┴────────┐
                │  Connection    │            │     Queue       │            │     Topic       │
                │   Service      │            │    Service      │            │    Service      │
                └───────┬────────┘            └────────┬────────┘            └────────┬────────┘
                        │                              │                              │
                        └──────────────────┬───────────┘                              │
                                          │                                  ┌────────┴────────┐
                                          │                                  │     Broker      │
                                          │                                  │    Service      │
                                          │                                  └────────┬────────┘
                                          │                                           │
                                          └────────┬──────────────────────────────----┘
                                                   │
                                          ┌────────┴────────┐
                                          │   Core Client   │
                                          │ (HTTP + Utils)  │
                                          └─────────────────┘

Project Structure

activemq-mcp-server/
├── 📁 bin/
│   └── cli.js                     # Command-line interface entry point
├── 📁 src/
│   ├── 📁 core/                   # Core business logic layer
│   │   ├── 📁 client/             # HTTP client and infrastructure
│   │   │   ├── core-client.js     # ActiveMQ REST API client
│   │   │   └── index.js           # Client exports
│   │   ├── 📁 service/            # Domain services
│   │   │   ├── activemq-facade.js # Unified facade interface
│   │   │   ├── broker-service.js  # Broker management operations
│   │   │   ├── connection-service.js # Connection lifecycle
│   │   │   ├── queue-service.js   # Queue operations
│   │   │   ├── topic-service.js   # Topic operations
│   │   │   └── index.js           # Service exports
│   │   ├── connection-manager.js  # Multi-broker connection registry
│   │   └── connection.js          # Individual connection wrapper
│   ├── 📁 mcp/                    # MCP protocol layer
│   │   ├── 📁 handlers/           # Tool implementation handlers
│   │   │   ├── broker-handlers.js # Broker management tools
│   │   │   ├── connection-handlers.js # Connection management tools
│   │   │   ├── queue-handlers.js  # Queue operation tools
│   │   │   ├── topic-handlers.js  # Topic operation tools
│   │   │   └── index.js           # Handler coordination
│   │   └── tools.js               # MCP tool definitions
│   ├── 📁 utils/                  # Shared utilities
│   │   ├── config.js              # Configuration management
│   │   └── logger.js              # Structured logging
│   └── server.js                  # MCP server entry point
├── 📁 test/
│   └── 📁 integration/            # Integration tests with real ActiveMQ
│       ├── 📁 service/            # Service layer tests
│       │   ├── broker-service.test.js
│       │   ├── connection-service.test.js
│       │   ├── queue-service.test.js
│       │   └── topic-service.test.js
│       └── 📁 setup/              # Test configuration
│           └── activemq-config.js
├── 📁 scripts/                    # Development scripts
│   └── wait-for-activemq.sh       # Test environment setup
├── 📁 .github/workflows/          # CI/CD automation
│   ├── ci.yml                     # Continuous integration
│   └── publish.yml                # NPM publishing
├── 📁 config files/               # Configuration examples
│   ├── activemq-config.json.example
│   └── config.example.json
├── docker-compose.test.yml        # Test environment setup
├── package.json                   # Project metadata and dependencies
├── CLAUDE.md                      # Development documentation
└── README.md                      # User documentation

Architecture Benefits

• 🏗️ Clean Separation: Infrastructure, business logic, and coordination layers
• 🔄 Composition Pattern: Services compose shared infrastructure, no inheritance
• 🎯 Single Responsibility: Each component has a focused, well-defined purpose
• 🧪 Testable Design: Integration tests with real ActiveMQ brokers
• 📈 Scalable: Easy to extend with new tools and services
• 🛡️ Reliable: REST API communication with connection pooling and health checks

Configuration

Environment Variables

Standard Environment Variables

Multiple Broker Environment Variables

For multiple broker connections, use the pattern {CONNECTION_NAME}_ACTIVEMQ_{PARAMETER}:

Examples:

# Production ActiveMQ broker
export PROD_ACTIVEMQ_HOST=prod-broker.company.com
export PROD_ACTIVEMQ_PORT=8161
export PROD_ACTIVEMQ_USERNAME=prod_user
export PROD_ACTIVEMQ_PASSWORD=prod_password
export PROD_ACTIVEMQ_SSL=true

# Development ActiveMQ broker
export DEV_ACTIVEMQ_HOST=localhost
export DEV_ACTIVEMQ_PORT=8161
export DEV_ACTIVEMQ_USERNAME=admin
export DEV_ACTIVEMQ_PASSWORD=admin

# Staging ActiveMQ broker
export STAGING_ACTIVEMQ_HOST=staging-broker.company.com
export STAGING_ACTIVEMQ_PORT=8161
export STAGING_ACTIVEMQ_USERNAME=staging_user
export STAGING_ACTIVEMQ_PASSWORD=staging_password

🔒 Security Advantage: This pattern allows you to configure multiple brokers securely using only environment variables, avoiding the need for configuration files that AI agents might access.

Configuration File Format

The configuration file supports multiple broker connections:

{
	"connection_name": {
		"host": "broker-host",
		"port": 8161,
		"username": "optional-username",
		"password": "optional-password",
		"ssl": false
	}
}

Configuration Loading Behavior

Configuration is loaded automatically in priority order - the system uses the first existing file and stops looking:

1. ./activemq-config.json (highest priority)
2. ./config.json
3. Path specified in ACTIVEMQ_CONFIG_PATH environment variable (lowest priority)

Important: Only one configuration file is loaded - there's no merging between files.

Environment Variables vs Configuration Files

Environment variables work differently from configuration files:

• Configuration files: Define named connections (e.g., "production", "staging")
• Environment variables: Always create a "default" connection that supplements any file-based config

Configuration Examples

Example 1: File Priority

# If both files exist:
./activemq-config.json  ← This file is loaded
./config.json           ← This file is ignored

Example 2: Environment Variables + File

File: activemq-config.json

{
  "production": {
    "host": "prod-broker.com",
    "port": 8161,
    "username": "prod_user",
    "password": "prod_pass"
  }
}

Environment Variables:

export ACTIVEMQ_HOST=localhost
export ACTIVEMQ_USERNAME=admin
export ACTIVEMQ_PASSWORD=admin

Result: Two connections available:

• production (from file)
• default (from environment variables)

Example 3: Custom Config Path

export ACTIVEMQ_CONFIG_PATH=/etc/activemq/my-config.json
# Only loads if ./activemq-config.json and ./config.json don't exist

Connection Parameters

• host (required): ActiveMQ broker hostname or IP address
• port (optional): Web console port (default: 8161)
• username (optional): Authentication username
• password (optional): Authentication password
• ssl (optional): Enable SSL/TLS connection (default: false)

Claude Integration

Claude Desktop Configuration

Add the ActiveMQ MCP server to your Claude Desktop by editing the MCP configuration file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Environment Variables (Recommended for Security)

{
  "mcpServers": {
    "activemq": {
      "command": "npx",
      "args": ["activemq-mcp-server"],
      "env": {
        "ACTIVEMQ_HOST": "localhost",
        "ACTIVEMQ_PORT": "8161",
        "ACTIVEMQ_USERNAME": "admin",
        "ACTIVEMQ_PASSWORD": "admin"
      }
    }
  }
}

🔒 Security Note: Environment variables are more secure than configuration files since AI agents can potentially access the file system, but environment variables are isolated to the MCP server process.

Option 1b: Multiple Brokers via Environment Variables (Secure Multi-Broker Setup)

{
  "mcpServers": {
    "activemq": {
      "command": "npx",
      "args": ["activemq-mcp-server"],
      "env": {
        "PROD_ACTIVEMQ_HOST": "prod-broker.company.com",
        "PROD_ACTIVEMQ_PORT": "8161",
        "PROD_ACTIVEMQ_USERNAME": "prod_user",
        "PROD_ACTIVEMQ_PASSWORD": "prod_password",
        "PROD_ACTIVEMQ_SSL": "true",
        "DEV_ACTIVEMQ_HOST": "localhost",
        "DEV_ACTIVEMQ_PORT": "8161",
        "DEV_ACTIVEMQ_USERNAME": "admin",
        "DEV_ACTIVEMQ_PASSWORD": "admin",
        "STAGING_ACTIVEMQ_HOST": "staging-broker.company.com",
        "STAGING_ACTIVEMQ_PORT": "8161",
        "STAGING_ACTIVEMQ_USERNAME": "staging_user",
        "STAGING_ACTIVEMQ_PASSWORD": "staging_password"
      }
    }
  }
}

Environment Variable Pattern: Use {CONNECTION_NAME}_ACTIVEMQ_{PARAMETER} format where:

• {CONNECTION_NAME} is the unique identifier for your broker (e.g., PROD, DEV, STAGING)
• {PARAMETER} is the broker parameter (HOST, PORT, USERNAME, PASSWORD, SSL)

🔒 Security Benefit: This approach keeps all sensitive credentials in environment variables while supporting multiple brokers without configuration files.

Option 2: Configuration File (Multiple Brokers)

{
  "mcpServers": {
    "activemq": {
      "command": "npx",
      "args": ["activemq-mcp-server"],
      "env": {
        "ACTIVEMQ_CONFIG_PATH": "/path/to/your/activemq-config.json"
      }
    }
  }
}

Claude Code Configuration

Add to your .mcp.json file in your project root:

Option 1: Environment Variables (Recommended for Security)

{
  "mcpServers": {
    "activemq": {
      "command": "npx",
      "args": ["activemq-mcp-server"],
      "env": {
        "ACTIVEMQ_HOST": "localhost",
        "ACTIVEMQ_PORT": "8161",
        "ACTIVEMQ_USERNAME": "admin",
        "ACTIVEMQ_PASSWORD": "admin"
      }
    }
  }
}

🔒 Security Note: Environment variables are more secure than configuration files since AI agents can potentially access the file system, but environment variables are isolated to the MCP server process.

Option 1b: Multiple Brokers via Environment Variables (Secure Multi-Broker Setup)

{
  "mcpServers": {
    "activemq": {
      "command": "npx",
      "args": ["activemq-mcp-server"],
      "env": {
        "PROD_ACTIVEMQ_HOST": "prod-broker.company.com",
        "PROD_ACTIVEMQ_PORT": "8161",
        "PROD_ACTIVEMQ_USERNAME": "prod_user",
        "PROD_ACTIVEMQ_PASSWORD": "prod_password",
        "PROD_ACTIVEMQ_SSL": "true",
        "DEV_ACTIVEMQ_HOST": "localhost",
        "DEV_ACTIVEMQ_PORT": "8161",
        "DEV_ACTIVEMQ_USERNAME": "admin",
        "DEV_ACTIVEMQ_PASSWORD": "admin",
        "ANALYTICS_ACTIVEMQ_HOST": "analytics-broker.company.com",
        "ANALYTICS_ACTIVEMQ_PORT": "8161",
        "ANALYTICS_ACTIVEMQ_USERNAME": "analytics_user",
        "ANALYTICS_ACTIVEMQ_PASSWORD": "analytics_password"
      }
    }
  }
}

Environment Variable Pattern: Use {CONNECTION_NAME}_ACTIVEMQ_{PARAMETER} format where:

• {CONNECTION_NAME} is the unique identifier for your broker (e.g., PROD, DEV, ANALYTICS)
• {PARAMETER} is the broker parameter (HOST, PORT, USERNAME, PASSWORD, SSL)

🔒 Security Benefit: This approach keeps all sensitive credentials in environment variables while supporting multiple brokers without configuration files.

Option 2: Configuration File (Multiple Brokers)

{
  "mcpServers": {
    "activemq": {
      "command": "npx",
      "args": ["activemq-mcp-server"],
      "env": {
        "ACTIVEMQ_CONFIG_PATH": "./activemq-config.json"
      }
    }
  }
}

For both options above, when using a configuration file, create an activemq-config.json file:

{
  "development": {
    "host": "localhost",
    "port": 8161,
    "username": "admin",
    "password": "admin"
  },
  "staging": {
    "host": "staging-activemq.company.com",
    "port": 8161,
    "username": "stage_user",
    "password": "stage_pass"
  }
}

After configuration, restart Claude Desktop or reload Claude Code to enable ActiveMQ management capabilities.

MCP Tools

The server exposes the following tools for AI interaction:

Connection Management

list_connections

List all configured broker connections.

{
	"name": "list_connections"
}

connect_broker

Connect to an ActiveMQ broker with manual configuration.

{
	"name": "connect_broker",
	"arguments": {
		"connectionId": "mybroker",
		"host": "broker.example.com",
		"port": 8161,
		"username": "user",
		"password": "pass",
		"maxReconnectAttempts": 5,
		"reconnectDelay": 5000
	}
}

Parameters:

• connectionId (required): Unique identifier for the connection
• host (optional): ActiveMQ broker hostname or IP address (default: "localhost")
• port (optional): ActiveMQ web console port (default: 8161)
• username (optional): Username for authentication
• password (optional): Password for authentication
• maxReconnectAttempts (optional): Maximum number of reconnection attempts (default: 5)
• reconnectDelay (optional): Delay between reconnection attempts in milliseconds (default: 5000)

connect_from_config

Connect to an ActiveMQ broker using a named configuration from config file.

{
	"name": "connect_from_config",
	"arguments": {
		"configName": "production",
		"connectionId": "prod-broker"
	}
}

show_config

Show all ActiveMQ broker configurations available in the config file.

{
	"name": "show_config"
}

remove_connection

Remove a broker connection.

{
	"name": "remove_connection",
	"arguments": {
		"connectionId": "mybroker"
	}
}

test_connection

Test connectivity to a broker without adding it.

{
	"name": "test_connection",
	"arguments": {
		"host": "broker.example.com",
		"port": 8161,
		"username": "user",
		"password": "pass"
	}
}

connection_info

Get detailed information about a specific connection.

{
	"name": "connection_info",
	"arguments": {
		"connectionId": "mybroker"
	}
}

health_status

Get health status of all connections.

{
	"name": "health_status"
}

Queue Operations

list_queues

List all queues for a connection.

{
	"name": "list_queues",
	"arguments": {
		"connectionId": "mybroker"
	}
}

queue_info

Get queue statistics and information.

{
	"name": "queue_info",
	"arguments": {
		"connectionId": "mybroker",
		"queueName": "my.queue"
	}
}

send_message

Send a message to a queue or topic.

{
	"name": "send_message",
	"arguments": {
		"connectionId": "mybroker",
		"destination": "/queue/my.queue",
		"message": "Hello, World!",
		"headers": {
			"priority": "5",
			"custom-header": "value"
		}
	}
}

consume_message

Consume a message from a queue.

{
	"name": "consume_message",
	"arguments": {
		"connectionId": "mybroker",
		"queueName": "my.queue",
		"timeout": 5000,
		"autoAck": true,
		"clientId": "consumer-123",
		"selector": "priority > 5"
	}
}

Parameters:

• connectionId (required): ID of the connection
• queueName (required): Name of the queue to consume from
• timeout (optional): Timeout in milliseconds to wait for a message (default: 5000)
• autoAck (optional): Automatically acknowledge the message (default: true)
• clientId (optional): Client ID for persistent consumer sessions
• selector (optional): JMS message selector for filtering messages

browse_messages

Browse messages in a queue without consuming them.

{
	"name": "browse_messages",
	"arguments": {
		"connectionId": "mybroker",
		"queueName": "my.queue",
		"limit": 10
	}
}

purge_queue

Remove all messages from a queue.

{
	"name": "purge_queue",
	"arguments": {
		"connectionId": "mybroker",
		"queueName": "my.queue",
		"confirm": true
	}
}

Topic Operations

list_topics

List all topics for a connection.

{
	"name": "list_topics",
	"arguments": {
		"connectionId": "mybroker"
	}
}

publish_message

Publish a message to a topic.

{
	"name": "publish_message",
	"arguments": {
		"connectionId": "mybroker",
		"topicName": "my.topic",
		"message": "Hello, Subscribers!",
		"headers": {
			"type": "notification"
		}
	}
}

subscribe_topic

Subscribe to a topic and receive messages.

{
	"name": "subscribe_topic",
	"arguments": {
		"connectionId": "mybroker",
		"topicName": "my.topic",
		"timeout": 10000,
		"maxMessages": 5
	}
}

Broker Information

broker_info

Get broker statistics and health information.

{
	"name": "broker_info",
	"arguments": {
		"connectionId": "mybroker"
	}
}

broker_stats

Get comprehensive broker statistics for all connections.

{
	"name": "broker_stats"
}

system_status

Get overall system status and performance metrics.

{
	"name": "system_status"
}

Backup and Migration

export_connections

Export connection configurations for backup.

{
	"name": "export_connections"
}

import_connections

Import connection configurations from backup.

{
	"name": "import_connections",
	"arguments": {
		"connections": {
			"imported_broker": {
				"host": "new-broker.example.com",
				"port": 8161
			}
		},
		"overwrite": false
	}
}

Command Line Interface

Start Server

# Basic start
npx activemq-mcp-server

# With custom log level
npx activemq-mcp-server --log-level debug

# Show configuration status
npx activemq-mcp-server config

# List available tools
npx activemq-mcp-server tools

Test Connection

# Test specific connection
npx activemq-mcp-server test --host broker.example.com --port 8161 --username user --password pass

List Available Tools

npx activemq-mcp-server tools

ActiveMQ Setup

Quick ActiveMQ Setup with Docker

# Run ActiveMQ Classic with web console enabled
docker run -d \
  --name activemq \
  -p 61616:61616 \
  -p 8161:8161 \
  apache/activemq-classic:latest

# Web console available at http://localhost:8161 (admin/admin)
# REST API available at http://localhost:8161/api/

ActiveMQ Configuration

The server uses ActiveMQ's REST API via the web console. Ensure the web console is enabled and accessible at port 8161 ( default configuration).

The REST API endpoints used:

• /api/message/ - Send and consume messages
• /api/jolokia/ - Broker management and statistics

Integration with AI Systems

Claude Desktop

Add to your Claude Desktop configuration:

{
	"mcpServers": {
		"activemq": {
			"command": "npx",
			"args": [
				"activemq-mcp-server"
			]
		}
	}
}

Other MCP Clients

The server implements the MCP protocol specification and should work with any compliant MCP client. It communicates via JSON-RPC over stdio.

Examples

Basic Message Operations

# Start server
npx activemq-mcp-server

# In your MCP client (AI assistant):
# "Send a message to the orders queue"
# "Check how many messages are in the notifications queue"
# "Consume the next message from the processing queue"
# "Browse the first 5 messages in the errors queue"

Multi-Broker Setup

# Create config.json with multiple brokers
cat > config.json << EOF
{
  "production": {
    "host": "prod-mq.example.com",
    "port": 8161,
    "username": "prod_user",
    "password": "prod_pass"
  },
  "staging": {
    "host": "stage-mq.example.com",
    "port": 8161,
    "username": "stage_user",
    "password": "stage_pass"
  }
}
EOF

# Start server
npx activemq-mcp-server

# Use connect_from_config tool to connect to specific brokers

Security Considerations

• Passwords in configuration files should be properly secured
• Use environment variables for sensitive credentials
• Consider network security when connecting to remote brokers
• Implement proper authentication and authorization on ActiveMQ brokers

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the file for details.

Support

• Report issues on GitHub Issues
• Check the ActiveMQ documentation
• Review MCP specification

Changelog

v1.0.0

• Initial release
• Full MCP protocol support
• Multiple broker connection management
• Comprehensive queue and topic operations
• Health monitoring and reconnection
• CLI interface and configuration system