ibm-mq-mcp

把 IBM MQ 的 REST API 暴露成 LLM 可调用的 MCP 工具的服务器。

1. 项目简介

本项目仿造 IBM 官方示例 ibm-messaging/mq-mcp-server， 把 IBM MQ 的管理与消息 REST API 包装成 MCP （Model Context Protocol）工具，供支持 MCP 的 LLM 客户端（如 Claude Code）直接调用。

原版是一个约 110 行的单文件示例，只暴露 dspmq / runmqsc 两个工具，配置全部硬编码， 错误一律返回 "Something went wrong!"。本项目在保留其「REST API → MCP 工具」核心思路的 前提下做了产品化改造：

• 工具数从 2 个扩展到 15 个，覆盖队列管理器、MQSC、对象查询、消息收发四类；

• 配置支持 CLI 参数 / 环境变量 / 默认值三级优先级，不再硬编码；

• 区分管理 API 与消息 API 两套凭据（详见下文「两套凭据」一节），这是实测出的真实限制， 原版没有涉及；

• 错误按四类（HTTP 层、认证、MQSC 业务失败、其他）分别解析，返回具体原因而不是笼统的 失败提示；

• 提供只读模式，可在生产环境中限制 LLM 只能查询、不能修改 MQ 配置。

所有关于 MQ REST API 行为的结论（见下文「已知限制」）均来自对真实 MQ 9.4.5.1 实例的 逐条探测，不是查文档推测得出的。

2. 快速开始

前提：本机已运行一个 IBM MQ 实例（例如 IBM 官方开发镜像 icr.io/ibm-messaging/mq:9.4.5.1-r1，MQ_DEV=true），mqweb 监听在 https://127.0.0.1:9443。

# 启动 MQ 容器（如果还没有运行）——本项目不负责容器生命周期，按需自行启动，例如：
# docker run --rm -e LICENSE=accept -e MQ_QMGR_NAME=QM1 -e MQ_DEV=true \
#   -e MQ_ADMIN_PASSWORD=admin -p 1414:1414 -p 9443:9443 \
#   icr.io/ibm-messaging/mq:9.4.5.1-r1

方式一：直接从 GitHub 运行（无需克隆）

uvx 会自动拉取源码、在临时环境里装好依赖并运行，用完即弃：

uvx --from git+https://github.com/moonfruit/ibm-mq-mcp ibm-mq-mcp

带参数同理，把它们接在命令后面即可：

uvx --from git+https://github.com/moonfruit/ibm-mq-mcp ibm-mq-mcp --read-only

想固定到某个版本或分支，在 URL 后加 @<ref>：

uvx --from git+https://github.com/moonfruit/ibm-mq-mcp@main ibm-mq-mcp

方式二：克隆后本地运行（要改代码时用这个）

git clone https://github.com/moonfruit/ibm-mq-mcp
cd ibm-mq-mcp
uv sync
uv run ibm-mq-mcp

两种方式都以 stdio 传输启动，默认连接 https://127.0.0.1:9443、管理凭据 admin/admin、忽略自签名证书校验。这组默认值正好对应 IBM 官方开发镜像， 连本机开发实例无需任何额外配置。

如果你的 uv 配了国内 PyPI 镜像，可能会遇到依赖解析失败（部分镜像同步不及时， 拿不到 mcp>=2.1.1）。临时指定官方源即可： UV_DEFAULT_INDEX=https://pypi.org/simple uvx --from git+... ibm-mq-mcp

3. 接入 Claude Code

在 Claude Code 的 MCP 配置中加入。直接引用 GitHub，无需克隆仓库：

{
  "mcpServers": {
    "ibm-mq": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/moonfruit/ibm-mq-mcp",
        "ibm-mq-mcp"
      ],
      "env": {
        "MQ_BASE_URL": "https://127.0.0.1:9443",
        "MQ_USERNAME": "admin",
        "MQ_PASSWORD": "admin",
        "MQ_MESSAGING_USERNAME": "app",
        "MQ_MESSAGING_PASSWORD": "admin"
      }
    }
  }
}

如果已经克隆到本地（比如你要改代码），把 command/args 换成本地路径：

      "command": "uv",
      "args": ["--directory", "/path/to/ibm-mq-mcp", "run", "ibm-mq-mcp"],

想让接进来的服务器只能读、不能改配置也不能销毁消息，在 env 里加 "MQ_READ_ONLY": "true"——此时只注册 10 个只读工具，run_mqsc 与消息写入类工具 根本不会出现在模型的工具列表里。

也可以复制 .env.example 为 .env 并按需修改（本项目不自动加载 .env， 需要配合 direnv 之类的工具或手动 export）。

4. 配置项

配置优先级：CLI 参数 > 环境变量 > 默认值。空字符串环境变量（如 MQ_PASSWORD=""） 视为未设置，会回退到默认值，避免被误当作显式的空密码。

--transport 支持 stdio、streamable-http、sse；stdio 下 --host/--port 不生效。日志一律写到 stderr（stdio 传输下 stdout 被 MCP 协议占用）。

5. 两套凭据——为什么消息工具默认用户名不是 admin

IBM MQ 把管理和消息拆成 MQWebAdmin 与 MQWebUser 两个互不包含的角色：

• 管理 API（队列管理器查询、MQSC、对象查询）要求 MQWebAdmin 角色；

• 消息 API（浏览/取走/发送/发布消息）要求 MQWebUser 角色。

实测对真实 MQ 9.4.5.1 实例逐条探测的结果：用 admin:admin 调用消息 API 会返回 403 MQWB0108E——IBM 开发镜像里的 admin 用户只有 MQWebAdmin 角色，没有 MQWebUser 角色。必须换用另一个用户（开发镜像里是 app:admin）才能调用消息 API。

因此本项目的默认值是两套凭据：

• 管理 API 默认 admin / admin；

• 消息 API 默认 app / admin。

如果只配置了 MQ_USERNAME/MQ_PASSWORD 而不配置 MQ_MESSAGING_USERNAME/ MQ_MESSAGING_PASSWORD，消息类工具（browse_message、get_message、 put_message、publish_message）大概率会在真实环境中因权限不足而失败——这不是 本项目的 bug，是 MQ 权限模型的设计如此。

6. 工具清单

只读工具（10 个，--read-only 模式下依然可用）

会改变状态的工具（5 个，--read-only 模式下不注册）

对象查询（list_queues/get_queue/list_channels/get_channel/ list_subscriptions/list_topics）统一通过 MQSC 的 runCommandJSON 实现， 而不是走 REST 资源路径，原因见下文「已知限制」第 3 条。

7. 安全提示

• 默认忽略服务器证书校验（MQ_VERIFY_SSL=false）。这是为了适配开发镜像的自签名 证书，开箱即用。生产环境应显式开启 --verify-ssl（或 MQ_VERIFY_SSL=true）， 否则连接可能被中间人劫持。

• 默认凭据 admin/admin 属于 MQWebAdmin 角色，具备完整管理权限。把本服务器接入 LLM 意味着模型可以调用 run_mqsc / run_mqsc_json 执行任意 MQSC 命令，包括 DELETE QLOCAL、STOP CHANNEL 等破坏性操作——这不是理论风险，是这两个工具的 设计使然。

• 生产环境建议改用只读账号，并在启动时加 --read-only（或 MQ_READ_ONLY=true）。只读模式下服务器只注册上述 10 个只读工具，run_mqsc、 run_mqsc_json、get_message、put_message、publish_message 根本不会出现 在 LLM 可见的工具列表里，而不是注册后再依赖权限报错——即便 LLM 尝试调用也无从 下手。

8. 已知限制

以下结论均对真实 MQ 9.4.5.1 实例逐条实测得出，不是查文档推测的：

1. browse_message 只能看到队首一条消息。MQ 的消息 REST API 没有游标分页， 实测连续 3 次 GET 请求返回的是同一条消息（messageId 相同、队列深度不变）。 需要遍历整个队列的场景，请改用原生 MQ 客户端（如 pymqi），本项目不支持。

2. 对象查询统一走 MQSC，而非 REST 资源路径。/admin/qmgr/{qm}/queue、 /channel、/subscription 这几个 REST 资源在 MQ 9.4 的 v3 管理 API 下已被 移除（实测返回 404 MQWB0116E），仅在 v1 API 保留。本项目改用 runCommandJSON 统一实现对象查询，覆盖面更广，对 MQ 版本差异也更不敏感—— 这一实现方式对 z/OS 队列管理器同样适用。

3. GET 是浏览、DELETE 才是取走，这是 MQ 消息 REST API 最反直觉的一点：GET 请求消息但不会从队列移除它，只有 DELETE 才会真正取走并从队列删除。本项目用 browse_ / get_ 两种工具命名前缀加以区分，避免 LLM 误用。

4. MQSC 命令失败时 HTTP 状态码仍是 200，失败信息藏在响应体的 overallCompletionCode 与错误详情字段（runCommandJSON 用 message 字段、runCommand 用 text 字段，两者不一致）里。本项目在客户端内部统一解析 为结构化错误，工具返回的文本会包含具体的 MQSC 错误原因。

5. 队列为空时 DELETE/GET 返回 204 且无响应体，这不是错误。本项目按状态码而非 响应体是否为空来判断队列是否有消息，避免把「取到一条正文为空的消息」误判为 「队列没有消息」。

9. 开发与测试

uv run ruff check .
uv run ruff format --check .
uv run pytest -v                  # 单元测试，默认跳过需要真实 MQ 实例的集成测试
uv run pytest -m integration -v   # 集成测试，需要本机有可访问的真实 MQ 实例