IBM i MCP Server

IBM i的MCP服务器和CLI

______________________________________________________________________

概述

这 IBM i MCP服务器 使AI代理能够通过模型上下文协议（MCP）与IBM i系统进行交互。它提供了对Db2 for i数据库的安全、基于SQL的访问，允许Claude、VSCode Copilot、Bob和自定义代理等AI应用程序查询系统信息、监控性能和执行数据库操作。

该回购还提供 ibmi 命令行界面 (@ibm/ibmi-cli)--一个终端第一兄弟，共享相同的YAML驱动的SQL工具引擎，因此相同的工具定义在MCP服务器和CLI中都适用。

它是如何工作的： AI客户端通过MCP连接→ 服务器执行YAML定义的SQL工具→ 结果通过Mapepire流回到AI代理。

\[！提示\] 📚 官方文件 | ⚠️ 文档正在积极开发中 文档在不断发展。请经常回来查看更新和新指南。如果缺少什么，请随时打开问题！

仓库结构

快速导航

• MCP服务器 -开始使用服务器
• IBM i命令行界面 -终端优先SQL和工具执行
• SQL工具 -创建自定义SQL工具
• AI代理 -使用代理框架
• Python客户端 -使用Python客户端进行测试
• 部署 -部署到生产环境
• 设置Mapepire -安装必备项

______________________________________________________________________

MCP服务器

MCP服务器使AI代理能够通过YAML定义的SQL工具在IBM i系统上执行SQL查询。

快速开始

先决条件：

• Mapepire 在IBM i（端口8076）上运行
• 已安装Node.js 18+

开始：

1. 克隆存储库：

   git clone https://github.com/IBM/ibmi-mcp-server.git
   cd ibmi-mcp-server

1. 配置您的IBM i连接：

   cat > .env  服务器将使用我们预先配置的工具：
   >
   > - 📊 性能监控（系统状态、内存池、活动作业）
   > - 请参阅 [工具指南](https://ibm-d95bab6e.mintlify.app/sql-tools/using-default-tools) 了解更多工具集。

   MCP服务器也可以在Docker容器中运行：

docker run --rm --name ibmi-mcp-server \ -v /path/to/tools/:/tools \ -v /path/to/.env/:/.env \ -e MCP_SERVER_CONFIG=/.env \ -p 3010:3010 ghcr.io/ibm/ibmi-mcp-server:latest

   > 将卷路径替换为工具目录的实际本地路径 `.env` 文件。

1. **验证它是否正在运行：**

# Check server health curl http://localhost:3010/healthz

# List available tools curl -X POST http://localhost:3010/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \ grep -o '"name":"[^"]*"' | sed 's/"name":"//g' | sed 's/"//g' | head -20

> \[！注意\]
> **[📖 完整服务器快速入门→](https://ibm-d95bab6e.mintlify.app/quickstart)**
>
> **下一步：**
>
> - [创建自定义工具](https://ibm-d95bab6e.mintlify.app/sql-tools/overview) -构建自己的SQL工具
> - [连接AI客户端](https://ibm-d95bab6e.mintlify.app/clients/overview) -与Claude、VSCode、Bob等集成。
>
> **其他链接：**
>
> - [服务器README](./packages/server/README.md)
> - [服务器配置](./packages/server/README.md#%EF%B8%8F-configuration)
> - 正在寻找终端CLI吗？跳转到 [IBM i命令行界面](#ibm-i-cli).

______________________________________________________________________

## IBM i命令行界面

MCP服务器的第一个兄弟终端。这 `ibmi` 命令共享相同的YAML驱动的SQL工具引擎，专为本地探索、即席查询、脚本自动化和CI/CD而设计，不需要MCP客户端。

### 快速开始

Install

npm i -g @ibm/ibmi-cli

Run a query

ibmi sql "SELECT * FROM SAMPLE.EMPLOYEE FETCH FIRST 5 ROWS ONLY"

Run a YAML-defined tool

ibmi tool system_status --tools ./tools/work-management.yaml

### 何时使用CLI与MCP服务器

这两个工具都位于同一个YAML工具引擎之上。这 **MCP服务器** 是构建AI代理和多客户端AI工作负载的事实上的接口。这 **命令行界面** 涵盖了其他所有内容，并且在一个完整的MCP服务器被过度使用时，也可以作为一个轻量级的、进程本地的替代方案。

|使用CLI时…|使用MCP服务器时|
|-------------------|--------------------------|
|你需要 **开发人员工效学** --一种交互式终端体验，用于查询Db2中的i、探索模式、在shell/CI中编写脚本或将结果导入其他工具|您 **构建人工智能代理或人工智能驱动的应用程序** 应该以对话方式调用IBM i工具（Claude Desktop、VSCode Copilot、Bob、Agno、LangChain、自定义代理）|
|你正在运行一个 **本地AI代理** 并希望CLI作为长期使用的MCP服务器的轻量级、进程内替代品，例如，一个为 `ibmi sql` 或 `ibmi tool` 作为其循环的一部分|您需要通过MCP协议获得远程服务器支持，包括 `stdio` 或HTTP传输|
|你想要 **快速同步执行** 针对具有丰富输出格式的一个或多个系统(`table`, `json`, `csv`, `markdown`，NDJSON），无需管理服务器进程|您需要 **共享网络访问** 具有身份验证、速率限制、结构化遥测和会话处理功能|

> 请参阅 [CLI代理集成指南](https://ibm-d95bab6e.mintlify.app/cli/agent-integration) 对于布线的具体示例 `ibmi` CLI进入本地AI代理。

> \[！注意\]
> **[📖 完整文档：CLI指南→](https://ibm-d95bab6e.mintlify.app/cli/overview)**
>
> **其他链接：**
>
> - [CLI自述文件](./packages/cli/README.md)
> - [入门指南](https://ibm-d95bab6e.mintlify.app/cli/getting-started)
> - [命令参考](https://ibm-d95bab6e.mintlify.app/cli/commands)
> - [输出格式](https://ibm-d95bab6e.mintlify.app/cli/output-formats)
> - [代理集成](https://ibm-d95bab6e.mintlify.app/cli/agent-integration)

______________________________________________________________________

## SQL工具

基于YAML的SQL工具配置，定义AI代理可以在IBM i系统上执行哪些查询。

### 快速开始

创建自定义工具文件 `tools/my-tools.yaml`:

sources: my-system: host: ${DB2i_HOST} user: ${DB2i_USER} password: ${DB2i_PASS} port: 8076 ignore-unauthorized: true

tools: system_status: source: ibmi-system description: "Overall system performance statistics with CPU, memory, and I/O metrics" parameters: [] statement: | SELECT * FROM TABLE(QSYS2.SYSTEM_STATUS(RESET_STATISTICS=>'YES',DETAILED_INFO=>'ALL')) X

toolsets: performance: tools: - system_status

使用您的工具运行服务器：

npx -y @ibm/ibmi-mcp-server@latest --tools ./tools/my-tools.yaml --transport http

### 可用工具集合

这 `tools/` 目录包括即用型配置：

- **性能监控** -系统状态、活动作业、CPU/内存指标
- **安全与审计** -用户配置文件、权限、安全事件
- **作业管理** -活动作业、作业队列、子系统
- **存储和IFS** -磁盘使用率、IFS对象、保存文件
- **数据库** -表、索引、约束、统计

> \[！注意\]
> **[📖 完整文档：工具指南→](https://ibm-d95bab6e.mintlify.app/sql-tools/overview)**
>
> **其他链接：**
>
> - [工具README](./tools/README.md)

______________________________________________________________________

## AI代理

使用流行框架通过MCP服务器与IBM i系统交互的预构建AI代理示例。

### 可用代理框架

|框架|语言|用例|文档|
|-----------|----------|----------|---------------|
| **AgNO** |Python |具有内置可观察性的生产就绪代理| [Agno自述](./agents/frameworks/agno/README.md) |
| **LangChain** |Python |复杂的工作流程和工具链| [LangChain自述](./agents/frameworks/langchain/README.md) |
| **谷歌ADK** |Python |谷歌AI生态系统集成| [谷歌ADK自述](./agents/frameworks/google_adk/README.md) |

### 代理人可以做什么

- **系统监控**：实时性能分析和健康检查
- **故障排除**：使用自然语言查询诊断问题
- **报告**：生成系统报告和见解
- **自动化**：通过对话执行管理任务

> \[！注意\]
> **[📖 完整文档：代理商指南→](https://ibm-d95bab6e.mintlify.app/agents/overview)**
>
> **其他链接：**
>
> - [代理商自述](./agents/README.md)

______________________________________________________________________

## Python客户端

用于测试和与MCP服务器交互的简单Python客户端示例。

import asyncio from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client

async def main(): # Connect to the IBM i MCP server with authentication async with streamablehttp_client("http://localhost:3010/mcp") as ( read_stream, write_stream, _, ): # Create a session using the authenticated streams async with ClientSession(read_stream, write_stream) as session: # Initialize the connection await session.initialize()

# List available tools (now authenticated with your IBM i credentials) tools = await session.list_tools() for i, tool in enumerate(tools.tools, 1): print(f"{i:2d}. {tool.name}") print(f" └─ {tool.description}")

# Execute a tool with authenticated IBM i access print("\n" + "=" * 80) print("SYSTEM ACTIVITY RESULT") print("=" * 80) result = await session.call_tool("system_activity", {})

print(result)

if __name__ == "__main__": asyncio.run(main())

> \[！注意\]
> **[📖 完整文档：客户端自述→](https://ibm-d95bab6e.mintlify.app/clients/overview)**
>
> **其他链接：**
>
> - [客户端自述](./client/README.md)

______________________________________________________________________

## 部署

容器化环境的生产就绪部署配置。

### 部署选项

- **Docker和Podman** -使用MCP Context Forge网关完成堆栈
- **OpenShift** -Kubernetes部署与S2I构建
- **生产特点** -HTTPS、身份验证、监控、缓存

> \[！注意\]
> **[📖 完整文档：部署指南→](./deployment/README.md)**

______________________________________________________________________

## 设置Mapepire

**在使用ibmi-mcp服务器之前，必须在ibmi系统上安装和配置Mapepire。**

### 什么是Mapepire？

[Mapepire](https://mapepire-ibmi.github.io/) 是用于IBMi的现代高性能数据库服务器，它通过WebSocket连接提供SQL查询执行功能。它充当现代应用程序架构（如MCP服务器、AI代理和REST API）和IBM i的Db2 for i数据库之间的网关。

### 为什么Mapepire支持AI和MCP工作负载

传统的IBM i数据库访问方法（ODBC、JDBC）与现代AI和MCP架构不太匹配，后者需要：

- **快速、轻便的连接**：AI代理进行频繁、短暂的数据库查询
- **WebSocket支持**：实现流式传输结果的实时双向通信
- **基于JSON的现代协议**：简化了与Types/JavaScript生态系统的集成
- **低延迟响应**：对于交互式人工智能对话和工具执行至关重要

Mapepire通过提供一个现代的、基于WebSocket的SQL查询接口来弥合这一差距，该接口针对AI代理和MCP工具的请求/响应模式进行了优化。

### 安装

**快速安装（IBM i SSH会话）：**

1. Install Mapepire using yum

yum install mapepire-server

2. Install Service Commander (if not already installed)

yum install service-commander

3. Start Mapepire service

sc start mapepire

> \[！注意\]
> **[📚 完整文档：Mapepire系统管理员指南→](https://mapepire-ibmi.github.io/guides/sysadmin/)**

> \[！重要\]
> **重要提示：**
>
> - 默认情况下，Mapepire在端口上运行 `8076`。配置时需要此端口号 `DB2i_PORT` 变量在你的 `.env` 文件。
> - 确保您的IBM i防火墙允许端口8076上的入站连接
> - 对于生产部署，配置SSL/TLS证书（请参阅官方指南）

______________________________________________________________________

______________________________________________________________________

## 许可证

此项目根据Apache许可证2.0获得许可。请参阅 [许可证](LICENSE) 文件以获取详细信息。