IBM Db2 for i

Db2 for i MCP Server

mcp-server-db2i 是一个面向 IBM i（AS/400）上 IBM Db2 for i（Db2i）的 Model Context Protocol (MCP) 服务。它让 Claude、Cursor 等 AI 助手能够通过 IBM i Access ODBC 驱动，或可选的 JT400 JDBC 驱动或基于 SSH 的 Mapepire，查询和检查 IBM i 数据库。

已在 MCP Registry 中以 io.github.Strom-Capital/mcp-server-db2i 收录。

网站： db2i-mcp.com，其中的博客介绍每个版本的更新。文档： docs.db2i-mcp.com。

架构

AI 客户端通过以下两种方式之一连接到 MCP 服务。Claude Desktop、Claude Code 和 Cursor 等本地客户端可以将其作为进程启动，并通过 stdio 通信。远程客户端通过 /mcp 上的 Streamable HTTP 连接，使用 OAuth 2.1（claude.ai 自定义连接器）或 bearer token（自定义 Agent）登录。本地客户端也可以使用 HTTP 端点。该服务使用 IBM i Access ODBC 驱动（默认，无需 Java）、可选的 JT400 JDBC 驱动（DB2I_DRIVER=jt400）或基于 SSH 的 Mapepire（DB2I_DRIVER=mapepire），对 Db2 for i 执行只读查询，适用于只能通过 SSH 访问的系统。一个服务可以通过连接配置文件访问多个 IBM i 系统，每个系统使用各自的驱动。

graph LR
    subgraph clients ["AI Clients"]
        local("Claude Desktop, Claude Code, Cursor")
        remote("claude.ai connectors")
        agents("Custom Agents")
    end

    subgraph server ["MCP Server"]
        stdio["stdio"]
        http["Streamable HTTP + Auth"]
        tools[["MCP Tools"]]
        profiles{{"System profiles"}}
        odbc["IBM i Access ODBC"]
        jdbc["JT400 JDBC (optional)"]
        mapepire["Mapepire over SSH (optional)"]
    end

    subgraph prod ["IBM i: prod"]
        db2prod[("Db2 for i")]
    end

    subgraph test ["IBM i: test"]
        db2test[("Db2 for i")]
    end

    subgraph dev ["IBM i: dev"]
        db2dev[("Db2 for i")]
    end

    local -->|local process| stdio
    local -.->|remote URL| http
    remote -->|OAuth 2.1| http
    agents -->|bearer token| http
    stdio & http --> tools
    tools --> profiles
    profiles --> odbc & jdbc & mapepire
    odbc -->|ODBC| db2prod
    jdbc -->|JDBC| db2test
    mapepire -->|SSH| db2dev

功能

• 只读 SQL 查询 - 安全执行 SELECT 语句并自动限制结果数量，还会设置查询超时，在 IBM i 上取消运行过久的语句
• 架构检查 - 列出所有架构／库，并可选择筛选
• 表元数据 - 列出表、描述列、查看索引和约束
• 视图检查 - 列出并查看数据库视图
• 安全设计 - 仅允许 SELECT 查询，通过环境变量提供凭据
• Docker 支持 - 以容器方式运行，便于部署
• HTTP 传输 - 通过 Streamable HTTP 提供 MCP 服务，并使用令牌身份验证，供远程客户端和 Agent 使用
• 远程客户端 OAuth - 内置 OAuth 2.1 登录，使用用户自己的 IBM i 配置文件，因此 claude.ai 自定义连接器可以连接。登录页面可展示贵公司的名称、徽标、颜色和语言（为贵公司自定义）
• 当前 MCP 规范 - 支持 2026-07-28，同时仍可服务于 2025 年前后的无状态客户端
• 双传输方式 - 同时运行 stdio 和 HTTP
• 多个系统 - 通过 DB2I_PROFILES 从一个服务访问多个 IBM i 系统，每个系统都有自己的驱动程序、凭据和库允许列表。工具可接受可选的 system 参数。请参阅多个系统
• 仅 SSH 的系统 - 使用 DB2I_DRIVER=mapepire，访问仅开放 SSH 的 IBM i。Mapepire 在 SSH 会话中启动，无需安装服务端，并会检查主机密钥。请参阅使用 Mapepire 驱动程序
• 工具选择 - 启用或禁用单个工具，例如禁用 execute_query，仅保留元数据模式
• 业务 SQL 工具 - 从 YAML 加载只读 ERP 查询和表备注，并在服务启动前使用 mcp-server-db2i validate-tools 检查这些文件。请参阅业务 SQL 工具
• 服务说明 - 在每个会话开始时向模型发送查询必须遵守的规则，例如用于标记已删除行的标志。请参阅说明
• 聊天中的图表 - 支持 MCP Apps 的宿主会在工具调用下方以可排序网格显示查询结果，点击一次即可查看图表。用户要求绘制图表时，或 YAML 工具指定图表时，会直接打开图表。请参阅结果视图
• 紧凑响应 - 默认使用紧凑 JSON，也可使用 Markdown 表格以节省令牌
• 语句检查和 DDL - 验证对象名称、返回用于重建对象的 SQL，并列出依赖某个表的对象
• 目录搜索和分析 - 跨库查找表和列、检查日志记录，并分析表的行数和取值范围
• 列遮蔽 - 在查询结果中隐藏敏感列，或仅显示其最后四个字符。请参阅列遮蔽
• 查询导出 - 为用户提供查询结果的 CSV 或 Excel 文件：通过 stdio 提供文件路径，或通过 HTTP 提供短时有效的下载链接。行数据不会经过模型。请参阅查询导出
• 审计日志 - 将每次工具调用和登录记录为一行 JSON，默认对 SQL 进行哈希处理。也可选择记录模型每次调用的理由（MCP_TOOL_INTENT）。请参阅审计日志
• 工具重新加载 - YAML 工具文件更改时重新加载，设置 MCP_CUSTOM_TOOLS_WATCH=true 即可启用
• 资源和提示词 - 将表列和 DDL 作为 MCP 资源读取，并通过可探索库、说明表或编写查询的提示词开始操作。请参阅资源和提示词

快速开始

安装

npm install -g mcp-server-db2i

默认的 odbc 驱动需要机器上安装 unixODBC 和 IBM i Access ODBC Driver。无需 Java。其他驱动的包默认不会安装，因此请将它们添加到服务旁边：

npm install -g mcp-server-db2i node-jt400              # DB2I_DRIVER=jt400, needs a JDK to install and a JRE to run
npm install -g mcp-server-db2i @ibm/mapepire-js ssh2   # DB2I_DRIVER=mapepire, when only SSH reaches the IBM i

使用 npx 时，通过 -p 传入这些包，例如 npx -y -p mcp-server-db2i@latest -p node-jt400 mcp-server-db2i。请参阅安装 jt400 和 mapepire 包。

也可以使用 Docker：

docker build -t mcp-server-db2i .                  # odbc image (amd64; add --platform linux/amd64 on arm64)
docker build --target jt400 -t mcp-server-db2i .   # jt400 image (builds natively on arm64)

配置

创建 .env 文件，填写 IBM i 凭据：

DB2I_HOSTNAME=your-ibm-i-host.com
DB2I_USERNAME=your-username
DB2I_PASSWORD=your-password
DB2I_SCHEMA=your-default-schema  # Optional

客户端设置

将以下内容添加到 MCP 客户端配置中（例如 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "db2i": {
      "command": "npx",
      "args": ["-y", "mcp-server-db2i@latest"],
      "env": {
        "DB2I_HOSTNAME": "${env:DB2I_HOSTNAME}",
        "DB2I_USERNAME": "${env:DB2I_USERNAME}",
        "DB2I_PASSWORD": "${env:DB2I_PASSWORD}"
      }
    }
  }
}

这里使用环境变量展开，避免将凭据写入配置文件。请在 shell 配置文件（~/.zshrc 或 ~/.bashrc）中设置这些变量。

有关 Cursor、Claude Desktop、Claude Code 和 Docker 的设置选项，请参阅客户端设置指南。

没有 MCP 客户端？示例 Web 应用是一个浏览器聊天应用，提供结果表格、导出功能和业务 SQL 工具。用户使用自己的 IBM i 用户配置文件登录，并自行提供模型 API 密钥。

可用工具

工具	描述
execute_query	执行只读 SELECT 查询；可选提供 chart 提示，用于结果视图
export_query	将只读查询的所有行写入 CSV 或 XLSX 文件：通过 stdio 返回文件路径，通过 HTTP 返回短期有效的下载链接。除非设置了 EXPORT_ENABLED，否则此功能关闭
list_schemas	列出模式／库（可选筛选）
list_tables	列出模式中的表（可选筛选）
search_tables	在各库中按名称或描述查找表
search_columns	在各库中按名称或描述查找列
describe_table	获取详细的列信息
list_views	列出模式中的视图（可选筛选）
list_indexes	列出表的 SQL 索引
get_table_constraints	获取主键、外键和唯一约束
list_routines	列出库中的 SQL 过程和函数，包括语言、外部程序和 SQL 数据访问方式
describe_routine	获取过程或函数的参数、返回值或结果列，以及调用模板
validate_query	检查语句但不执行，包括目录名称
get_object_ddl	返回用于重建对象的 SQL DDL
get_related_objects	列出依赖于某个表的对象
get_journal_info	列出每个表的日志、映像和主键，并标记复制工具无法读取的表
index_advice	列出查询优化器在某个库中要求的索引，按临时索引使用情况合并并排序
profile_table	从存储统计信息或扫描中获取行数、最后更改时间，以及每列的不同值数和空值数
get_business_context	列出从 YAML 加载的业务描述、行筛选条件和关系
search_ibmi_services	按关键字或类别查找 IBM i 服务，并显示各服务加入的版本及示例查询

在支持 MCP Apps 的宿主中，execute_query、profile_table 和业务 SQL 工具的结果会在工具调用下方以网格和图表形式打开。请参阅结果视图。

筛选语法

列表工具支持模式匹配：

• CUST - 包含“CUST”
• CUST* - 以“CUST”开头
• *LOG - 以“LOG”结尾

资源和提示词

支持 MCP 资源的客户端无需调用工具即可读取表的上下文，并能在你输入时补全库名和表名。

资源	内容	注册条件
db2i://{schema}/{table}	从目录读取的列信息，以及 YAML 业务描述、列注释和关系	启用 describe_table
db2i://{schema}/{table}/ddl	来自 QSYS2.GENERATE_SQL 的 SQL，可用于重建表、视图或别名	启用 get_object_ddl
db2i://business-context	从 MCP_CUSTOM_TOOLS 加载的所有注释	启用 get_business_context
ui://db2i/result	MCP Apps 在工具结果下方显示的结果视图	开启 MCP_UI_ENABLED（默认开启）

resources/list 会提供已添加注释的表，例如 db2i://MYLIB/ORDERS。名称中的 # 和其他保留字符须进行百分号编码（ORD%23X 表示 ORD#X）。QUERY_ALLOWED_SCHEMAS 之外的库会被拒绝，并返回与 execute_query 相同的消息；自动补全也只会提供允许的库。查询 IBM i 的读取和自动补全操作会计入速率限制，读取操作也会写入审计日志。自动补全只获取一次库名列表，并缓存 60 秒，因此输入名称只需执行一次查询，而非每敲一个字符都执行一次。

提示词	参数	用途
explore_library	schema	列出表，描述核心表，并概述它们之间的关联
explain_table	schema、table	用通俗语言说明行、列、键和关系
write_query	question、schema、table	使用表中的实际列和 YAML 关系编写一条 SELECT，然后在相应工具已启用时验证并运行

只有在提示词要求模型调用的工具已启用时，该提示词才会列出：explore_library 需要 list_tables 和 describe_table，另外两个需要 describe_table。这些提示词都不会要求执行写入操作。

使用场景

我曾在一些项目中使用此服务，这些项目的源系统是运行在 IBM i 上的 Iptor DC1 ERP。同样的模式也适用于任何 IBM i ERP。

• 构建 REST API - Agent 查找 ERP 表和键，使用 validate_query 检查 SQL，在样本行上测试，然后编写端点。
• 面向 BI 的 ETL 和 ELT 流水线 - 分析源表，使用 get_object_ddl 生成暂存 DDL，并为数据仓库起草增量提取逻辑和代码映射。
• 近实时复制到 BI - 检查哪些表已记录日志，以及记录了哪些映像，然后再使用 Fivetran 等基于日志的工具将变更流式传输到数据仓库。
• 临时分析 - 将 Claude 或 Cursor 直接连接到 ERP，用通俗语言询问业务问题，并使用经过审核的 Business SQL 工具和敏感字段列屏蔽功能。

请参阅使用场景，了解示例提示词和每个场景对应的防护措施。

示例用法

连接后，你可以向 AI 助手提问：

• “列出所有包含‘PROD’的架构”
• “显示 MYLIB 架构中的表”
• “描述 MYLIB/CUSTOMERS 中的列”
• “ORDERS 表上有哪些索引？”
• “运行此查询：SELECT * FROM MYLIB.CUSTOMERS WHERE STATUS = 'A'”
• “在 MYLIB 中查找订单头表和订单行表，并编写一个 GET /orders/:orderNo 端点”
• “起草一份增量提取方案，提取自昨天以来发生变更的 MYLIB.ORDERHDR 行”

文档

指南	描述
工具、资源和提示词	内置工具、筛选语法、MCP 资源和提示词
HTTP 传输	HTTP API、身份验证和协议版本
配置	所有环境变量和驱动程序选项
安全	凭据、速率限制、查询验证
业务 SQL 工具	用于订单、分类账和主数据的 YAML 工具
用例	REST API、BI 管道、复制和临时分析
客户端设置	Cursor、Claude、Claude Code 设置
示例 Web 应用	使用自有模型密钥和 IBM i 登录的浏览器聊天
Docker 指南	容器部署
开发	贡献和本地设置

兼容性

• IBM i V7R3 及更高版本（推荐 V7R5）
• validate_query 和 execute_query 的解析检查需要 QSYS2.PARSE_STATEMENT（IBM i 7.3 搭配 Db2 PTF 组 SF99703 级别 3，或 IBM i 7.4 及更高版本）
• get_related_objects 需要 IBM i 7.3 Technology Refresh 9、IBM i 7.4 Technology Refresh 3 或更高版本
• get_journal_info 需要 QSYS2.OBJECT_STATISTICS 的日志列（IBM i 7.3 Technology Refresh 2 或更高版本）
• search_ibmi_services 需要 QSYS2.SERVICES_INFO，它随 Db2 for i PTF 组提供
• 失败语句的 cause 和 recovery 来自 SYSTOOLS.SQLCODE_INFO。如果没有该对象，错误只会返回 SQLSTATE、SQLCODE 和消息
• Node.js 22 或更高版本
• 对于默认的 odbc 驱动程序，需要 unixODBC 和 IBM i Access ODBC Driver；对于可选的 jt400 驱动程序，安装时需要 JDK，运行时需要 JRE 11 或更高版本；对于可选的 mapepire 驱动程序，需要 SSH 访问权限，且 IBM i 上需要 Java 8 或更高版本（参见数据库驱动程序）
• MCP 规范 2026-07-28，以及 2025 年修订版中的无状态客户端（截至 2025-11-25）

相关项目

• IBM ibmi-mcp-server - IBM 为 IBM i 系统提供的官方 MCP 服务。提供基于 YAML 的 SQL 工具定义和 AI Agent 框架。需要 Mapepire。本项目的 mapepire 驱动程序使用 Mapepire 的 SSH 模式，无需在 IBM i 上运行 Mapepire 服务。

贡献

欢迎贡献！有关设置说明，请参见开发指南。

许可证

MIT 许可证——详情请参见 LICENSE。

商标

IBM、IBM i 和 Db2 是 International Business Machines Corporation 的商标。本项目与 IBM 无关联，也未获得 IBM 认可。

致谢

• node-jt400 - Node.js 的 JT400 JDBC 驱动程序封装
• node-odbc - Node.js 的 ODBC 绑定，由 IBM 维护
• mapepire-js - Node.js 的 Mapepire 客户端，由 IBM 维护
• Model Context Protocol - 协议规范
• @modelcontextprotocol/server - 官方 TypeScript SDK（规范 2026-07-28，支持 2025 年时期的无状态客户端）