mcp-ibm-mq-server

A governed Model Context Protocol (MCP) server that lets AI agents read and send IBM MQ messages without bypassing enterprise controls.

Most AI agent demos connect straight to core systems with a service account. That never gets past security in a bank, a hospital or a government agency. This server puts a narrow, audited tool layer between the agent and IBM MQ, so Claude, Copilot, OpenAI or Gemini agents can work with existing queues while the queue manager, its channels and the core systems stay unchanged.

It is the reference implementation for issue #1 of my newsletter, Integration to Intelligence: "Your AI agent shouldn't touch your core systems directly."

Why this design

Related MCP server: xT MCP Server

Tools

Quick start (no IBM MQ needed)

pip install -e ".[dev]"
MQ_FAKE=true MQ_READ_QUEUES=ORDERS.STATUS mcp-ibm-mq-server

MQ_FAKE=true uses an in-memory queue manager seeded with a sample message, so you can try the tools from any MCP client in a minute.

Run against a real IBM MQ

1. Start IBM's free developer queue manager (creates QM1, DEV.APP.SVRCONN and DEV.QUEUE.1):

   cp .env.example .env        # set MQ_PASSWORD
   docker compose up -d

2. Install the IBM MQ client libraries (IBM MQ redistributable client) and the mq extra:

   pip install -e ".[mq]"

3. Point the server at the queue manager and choose what the agent may do:

   export MQ_QMGR=QM1 MQ_CONN_INFO="localhost(1414)" MQ_CHANNEL=DEV.APP.SVRCONN
   export MQ_USER=app MQ_PASSWORD=...           # from .env, never committed
   export MQ_READ_QUEUES=DEV.QUEUE.1
   mcp-ibm-mq-server

Connect it to Claude Desktop

Add to claude_desktop_config.json (see examples/claude_desktop_config.json):

{
  "mcpServers": {
    "ibm-mq": {
      "command": "mcp-ibm-mq-server",
      "env": {
        "MQ_FAKE": "true",
        "MQ_READ_QUEUES": "ORDERS.STATUS",
        "MQ_AGENT_ID": "claude-desktop"
      }
    }
  }
}

Then ask: "What's on the ORDERS.STATUS queue?"

Configuration

Production notes

• Run the server behind your API gateway (Apigee, Azure API Management, Kong, IBM API Connect) when exposing it over HTTP, so agents inherit OAuth identity, rate limits and logging. Use stdio for local clients.

• Give the MQ user least privilege with setmqaut (browse/inq on read queues, put on write queues only) and enable TLS and CHLAUTH on the channel. The policy here is a second line of defence, not a replacement for MQ security.

• Ship the audit log to your SIEM; correlate on audit_id, msg_id and MQ_AGENT_ID.

• Keep a human-in-the-loop step for high-risk puts (payments, account changes) in the agent workflow.

Tests

pip install -e ".[dev]" && pytest

Tests use the in-memory client, so they run anywhere, including CI.

Roadmap

• Streamable HTTP transport with OAuth (MCP authorization spec)

• JSON-schema validation of message bodies per queue

• Approval hook for writes above a risk threshold

• IBM MQ REST API client option (no native client libraries)

About

Built by Aashish Malaviya, Principal Architect at Arch SI (Architecture · System Intelligence). 20+ years of enterprise integration on IBM MQ, ACE and DataPower across banking, security services and government, now connecting AI agents to the systems they act on.

LinkedIn · archsi.io

License

MIT