Skip to content
Back to search

ibmi-mcp-server

MCP server for IBM i systems

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/IBM/ibmi-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/IBM/ibmi-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ibm--ibmi-mcp-server/badge.svg)](/listings/ibm--ibmi-mcp-server)

HTML

<a href="/listings/ibm--ibmi-mcp-server"><img src="/api/listings/ibm--ibmi-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites:** - [Mapepire](#setup-mapepire) running on IBM i (port 8076) - Node.js 18+ installed

**Get Started:**

1. **Clone the repository:**

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

2. **Configure your IBM i connection:**

   cat > .env << 'EOF'
   DB2i_HOST=your-ibmi-host.com
   DB2i_USER=your-username
   DB2i_PASS=your-password
   DB2i_PORT=8076
   DB2i_IGNORE_UNAUTHORIZED=true
   EOF

3. **Start the server:**

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

> The server will use our pre-configured tools for: > - πŸ“Š Performance monitoring (system status, memory pools, active jobs) > - See the [Tools Guide](https://ibm-d95bab6e.mintlify.app/sql-tools/using-default-tools) for more toolsets.

The MCP server can also run in a Docker container:

   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

> Replace the volume paths with your actual local paths to the tools directory and `.env` file.

4. **Verify it's running:**

   # 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

> [!NOTE] > **[πŸ“– Full Server Quickstart β†’](https://ibm-d95bab6e.mintlify.app/quickstart)** > > **Next Steps:** > - [Create Custom Tools](https://ibm-d95bab6e.mintlify.app/sql-tools/overview) - Build your own SQL tools > - [Connect AI Clients](https://ibm-d95bab6e.mintlify.app/clients/overview) - Integrate with Claude, VSCode, Bob, etc. > > **Additional links:** > - [Server README](./packages/server/README.md) > - [Server Configuration](./packages/server/README.md#️-configuration) > - Looking for the terminal CLI instead? Jump to [IBM i CLI](#ibm-i-cli).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 374 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. ![alt text](docs/images/logo-2.png)
  3. [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue?style=flat-square)](https://www.typescriptlang.org/)
  4. [![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^2.4.0-green?style=flat-square)](https://github.com/modelcontextprotocol/typescript-sdk)
  5. [![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2026--07--28-lightgrey?style=flat-square)](https://modelcontextprotocol.io/specification/2026-07-28)
  6. [![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
  7. [![Status](https://img.shields.io/badge/Status-Stable-green?style=flat-square)](https://github.com/IBM/ibmi-mcp-server.git)
  8. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/IBM/ibmi-mcp-server)
  9. ![NPM Version](https://img.shields.io/npm/v/%40ibm%2Fibmi-mcp-server)
  10. **MCP server and CLI for IBM i**
  11. </div>
  12. ---
  13. ## Overview
  14. The **IBM i MCP Server** enables AI agents to interact with IBM i systems through the Model Context Protocol (MCP). It provides secure, SQL-based access to Db2 for i databases, allowing AI applications like Claude, VSCode Copilot, Bob, and custom agents to query system information, monitor performance, and execute database operations.
  15. This repo also ships the **`ibmi` CLI** ([`@ibm/ibmi-cli`](https://www.npmjs.com/package/@ibm/ibmi-cli)) β€” a terminal-first sibling that shares the same YAML-driven SQL tool engine, so the same tool definitions work in both the MCP server and the CLI.
  16. ![MCP Architecture](docs/images/mcp-arch.png)
  17. > **How it works:** AI clients connect via MCP β†’ Server executes YAML-defined SQL tools β†’ Results stream back to the AI agent through Mapepire.
  18. > [!TIP]
  19. > **πŸ“š [Official Documentation](https://ibm-d95bab6e.mintlify.app/) | ⚠️ Docs are under active development**
  20. >
  21. > The Docs are continuously evolving. Please check back frequently for updates and new guides. If there's something missing, feel free to open an issue!
  22. ### Repository Structure
  23. | Directory | Purpose | Documentation |
  24. |-----------|---------|---------------|
  25. | **`packages/server/`** | MCP server implementation (TypeScript) β€” `@ibm/ibmi-mcp-server` on npm | [Server README](./packages/server/README.md) |
  26. | **`packages/cli/`** | `ibmi` command-line interface β€” `@ibm/ibmi-cli` on npm, co-versioned with the server | [CLI README](./packages/cli/README.md) |
  27. | **`tools/`** | YAML-based SQL tool configurations | [Tools Guide](./tools/README.md) |
  28. | **`agents/`** | AI agent examples and integrations | [Agents Guide](./agents/README.md) |
  29. | **`client/`** | Python client examples for testing | [Client README](./client/README.md) |
  30. | **`deployment/`** | Docker, Podman, OpenShift configs | [Deployment Guide](./deployment/README.md) |
  31. ### Quick Navigation
  32. - [MCP Server](#mcp-server) - Get started with the server
  33. - [IBM i CLI](#ibm-i-cli) - Terminal-first SQL and tool execution
  34. - [SQL Tools](#sql-tools) - Create custom SQL tools
  35. - [AI Agents](#ai-agents) - Use agent frameworks
  36. - [Python Clients](#python-clients) - Test with Python clients
  37. - [Deployment](#deployment) - Deploy to production
  38. - [Setup Mapepire](#setup-mapepire) - Install prerequisite
  39. ---
  40. ## MCP Server
  41. The MCP Server enables AI agents to execute SQL queries on IBM i systems through YAML-defined SQL tools.
  42. ### Quick Start
  43. **Prerequisites:**
  44. - [Mapepire](#setup-mapepire) running on IBM i (port 8076)
  45. - Node.js 22.17+ installed
  46. **Get Started:**
  47. 1. **Clone the repository:**
  48. ```bash
  49. git clone https://github.com/IBM/ibmi-mcp-server.git
  50. cd ibmi-mcp-server
  51. ```
  52. 2. **Configure your IBM i connection:**
  53. ```bash
  54. cat > .env << 'EOF'
  55. DB2i_HOST=your-ibmi-host.com
  56. DB2i_USER=your-username
  57. DB2i_PASS=your-password
  58. DB2i_PORT=8076
  59. DB2i_IGNORE_UNAUTHORIZED=true
  60. EOF
  61. ```
  62. 3. **Start the server:**
  63. ```bash
  64. npx -y @ibm/ibmi-mcp-server@latest \
  65. --transport http \
  66. --tools ./tools/performance/performance.yaml
  67. ```
  68. > The server will use our pre-configured tools for:
  69. > - πŸ“Š Performance monitoring (system status, memory pools, active jobs)
  70. > - See the [Tools Guide](https://ibm-d95bab6e.mintlify.app/sql-tools/using-default-tools) for more toolsets.
  71. The MCP server can also run in a Docker container:
  72. ```bash
  73. docker run --rm --name ibmi-mcp-server \
  74. -v /path/to/tools/:/tools \
  75. -v /path/to/.env/:/.env \
  76. -e MCP_SERVER_CONFIG=/.env \
  77. -p 3010:3010 ghcr.io/ibm/ibmi-mcp-server:latest
  78. ```
  79. > Replace the volume paths with your actual local paths to the tools directory and `.env` file.
  80. 4. **Verify it's running:**
  81. ```bash
  82. # Check server health
  83. curl http://localhost:3010/healthz
  84. # List available tools
  85. curl -X POST http://localhost:3010/mcp \
  86. -H "Content-Type: application/json" \
  87. -H "Accept: application/json, text/event-stream" \
  88. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  89. grep -o '"name":"[^"]*"' | sed 's/"name":"//g' | sed 's/"//g' | head -20
  90. ```
  91. > [!NOTE]
  92. > **[πŸ“– Full Server Quickstart β†’](https://ibm-d95bab6e.mintlify.app/quickstart)**
  93. >
  94. > **Next Steps:**
  95. > - [Create Custom Tools](https://ibm-d95bab6e.mintlify.app/sql-tools/overview) - Build your own SQL tools
  96. > - [Connect AI Clients](https://ibm-d95bab6e.mintlify.app/clients/overview) - Integrate with Claude, VSCode, Bob, etc.
  97. >
  98. > **Additional links:**
  99. > - [Server README](./packages/server/README.md)
  100. > - [Server Configuration](./packages/server/README.md#️-configuration)
  101. > - Looking for the terminal CLI instead? Jump to [IBM i CLI](#ibm-i-cli).
  102. ---
  103. ## IBM i CLI
  104. A terminal-first sibling to the MCP server. The `ibmi` command shares the same YAML-driven SQL tool engine and is designed for local exploration, ad-hoc queries, scripted automation, and CI/CD β€” no MCP client required.
  105. ### Quick Start
  106. ```bash
  107. # Install
  108. npm i -g @ibm/ibmi-cli
  109. # Run a query
  110. ibmi sql "SELECT * FROM SAMPLE.EMPLOYEE FETCH FIRST 5 ROWS ONLY"
  111. # Run a YAML-defined tool
  112. ibmi tool system_status --tools ./tools/performance/performance.yaml
  113. ```
  114. ### When to use the CLI vs. the MCP Server
  115. Both tools sit on top of the same YAML tool engine. The **MCP Server** is the de facto interface for building AI agents and multi-client AI workloads. The **CLI** covers everything else β€” and also serves as a lightweight, process-local alternative when a full MCP server is overkill.
  116. | Use the CLI when… | Use the MCP Server when… |
  117. |-------------------|--------------------------|
  118. | You need **developer ergonomics** β€” an interactive terminal experience for querying Db2 for i, exploring schemas, scripting in shell/CI, or piping results into other tools | You are **building AI agents or AI-powered applications** that should call IBM i tools conversationally (Claude Desktop, VSCode Copilot, Bob, Agno, LangChain, custom agents) |
  119. | You are running a **local AI agent** and want the CLI as a lightweight, in-process alternative to a long-lived MCP server β€” e.g., a coding agent that shells out to `ibmi sql` or `ibmi tool` as part of its loop | You need remote server support over the MCP protocol, including `stdio` or HTTP transports |
  120. | You want **fast synchronous execution** against one or many systems with rich output formats (`table`, `json`, `csv`, `markdown`, NDJSON) and no server process to manage | You need **shared, networked access** with OAuth authentication, rate limiting, and structured telemetry |
  121. > See the [CLI Agent Integration guide](https://ibm-d95bab6e.mintlify.app/cli/agent-integration) for concrete examples of wiring the `ibmi` CLI into local AI agents.
  122. > [!NOTE]
  123. > **[πŸ“– Full Documentation: CLI Guide β†’](https://ibm-d95bab6e.mintlify.app/cli/overview)**
  124. >
  125. > **Additional links:**
  126. > - [CLI README](./packages/cli/README.md)
  127. > - [Getting Started](https://ibm-d95bab6e.mintlify.app/cli/getting-started)
  128. > - [Commands Reference](https://ibm-d95bab6e.mintlify.app/cli/commands)
  129. > - [Output Formats](https://ibm-d95bab6e.mintlify.app/cli/output-formats)
  130. > - [Agent Integration](https://ibm-d95bab6e.mintlify.app/cli/agent-integration)
  131. ---
  132. ## SQL Tools
  133. YAML-based SQL tool configurations that define what queries AI agents can execute on your IBM i system.
  134. ### Quick Start
  135. Create a custom tool file `tools/my-tools.yaml`:
  136. ```yaml
  137. sources:
  138. ibmi-system:
  139. host: ${DB2i_HOST}
  140. user: ${DB2i_USER}
  141. password: ${DB2i_PASS}
  142. port: 8076
  143. ignore-unauthorized: true
  144. tools:
  145. system_status:
  146. source: ibmi-system
  147. description: "Overall system performance statistics with CPU, memory, and I/O metrics"
  148. parameters: []
  149. statement: |
  150. SELECT * FROM TABLE(QSYS2.SYSTEM_STATUS(RESET_STATISTICS=>'YES',DETAILED_INFO=>'ALL')) X
  151. toolsets:
  152. performance:
  153. tools:
  154. - system_status
  155. ```
  156. Run the server with your tools:
  157. ```bash
  158. npx -y @ibm/ibmi-mcp-server@latest --tools ./tools/my-tools.yaml --transport http
  159. ```
  160. ### Available Tool Collections
  161. The `tools/` directory includes ready-to-use configurations:
  162. - **Performance Monitoring** (`performance/`) - System status, active jobs, memory pools, HTTP server stats
  163. - **Security Analysis** (`security/`) - Library list security assessment, authority checks, vulnerability detection
  164. - **System Administration** (`sys-admin/`) - Service discovery, schema browsing, PTF management
  165. - **Developer Tools** (`developer/`) - Object statistics, stale object detection
  166. - **Sample Data** (`sample/`) - Demonstration tools using the IBM i SAMPLE schema
  167. > [!NOTE]
  168. > **[πŸ“– Full Documentation: Tools Guide β†’](https://ibm-d95bab6e.mintlify.app/sql-tools/overview)**
  169. >
  170. > **Additional links:**
  171. > - [Tools README](./tools/README.md)
  172. ---
  173. ## AI Agents
  174. Pre-built AI agent examples using popular frameworks to interact with IBM i systems through the MCP Server.
  175. ### Available Agent Frameworks
  176. | Framework | Language | Use Case | Documentation |
  177. |-----------|----------|----------|---------------|
  178. | **Agno** | Python | Production-ready agents with built-in observability | [Agno README](./agents/frameworks/agno/README.md) |
  179. | **LangChain** | Python | Complex workflows and tool chaining | [LangChain README](./agents/frameworks/langchain/README.md) |
  180. | **Google ADK** | Python | Google AI ecosystem integration | [Google ADK README](./agents/frameworks/google_adk/README.md) |
  181. ### What Agents Can Do
  182. - **System Monitoring**: Real-time performance analysis and health checks
  183. - **Troubleshooting**: Diagnose issues using natural language queries
  184. - **Reporting**: Generate system reports and insights
  185. - **Automation**: Execute administrative tasks through conversation
  186. > [!NOTE]
  187. > **[πŸ“– Full Documentation: Agents Guide β†’](https://ibm-d95bab6e.mintlify.app/agents/overview)**
  188. >
  189. > **Additional links:**
  190. > - [Agents README](./agents/README.md)
  191. ---
  192. ## Python Clients
  193. Simple Python client examples for testing and interacting with the MCP Server.
  194. ```python
  195. import asyncio
  196. from mcp import ClientSession
  197. from mcp.client.streamable_http import streamablehttp_client
  198. async def main():
  199. # Connect to a local IBM i MCP server (no authentication)
  200. async with streamablehttp_client("http://localhost:3010/mcp") as (
  201. read_stream,
  202. write_stream,
  203. _,
  204. ):
  205. # Create a client session on the streams
  206. async with ClientSession(read_stream, write_stream) as session:
  207. # Initialize the connection
  208. await session.initialize()
  209. # List available tools
  210. tools = await session.list_tools()
  211. for i, tool in enumerate(tools.tools, 1):
  212. print(f"{i:2d}. {tool.name}")
  213. print(f" └─ {tool.description}")
  214. # Execute a tool
  215. print("\n" + "=" * 80)
  216. print("SYSTEM ACTIVITY RESULT")
  217. print("=" * 80)
  218. result = await session.call_tool("system_activity", {})
  219. print(result)
  220. if __name__ == "__main__":
  221. asyncio.run(main())
  222. ```
  223. > [!NOTE]
  224. > **[πŸ“– Full Documentation: Client README β†’](https://ibm-d95bab6e.mintlify.app/clients/overview)**
  225. >
  226. > **Additional links:**
  227. > - [Client README](./client/README.md)
  228. ---
  229. ## Deployment
  230. Production-ready deployment configurations for containerized environments.
  231. ### Deployment Options
  232. - **Docker & Podman** - Complete stack with MCP Context Forge Gateway
  233. - **OpenShift** - Kubernetes deployment with S2I builds
  234. - **Production Features** - HTTPS, authentication, monitoring, caching
  235. > [!NOTE]
  236. > **[πŸ“– Full Documentation: Deployment Guide β†’](./deployment/README.md)**
  237. ---
  238. ## Setup Mapepire
  239. **Before you can use the ibmi-mcp-server, you must install and configure Mapepire on your IBM i system.**
  240. ### What is Mapepire?
  241. [Mapepire](https://mapepire-ibmi.github.io/) is a modern, high-performance database server for IBM i that provides SQL query execution capabilities over WebSocket connections. It acts as a gateway between modern application architectures (like MCP servers, AI agents, and REST APIs) and IBM i's Db2 for i database.
  242. ### Why Mapepire Enables AI and MCP Workloads
  243. Traditional IBM i database access methods (ODBC, JDBC) don't align well with modern AI and MCP architectures that require:
  244. - **Fast, lightweight connections**: AI agents make frequent, short-lived database queries
  245. - **WebSocket support**: Enables real-time, bidirectional communication for streaming results
  246. - **Modern JSON-based protocols**: Simplifies integration with TypeScript/JavaScript ecosystems
  247. - **Low-latency responses**: Essential for interactive AI conversations and tool executions
  248. Mapepire bridges this gap by providing a modern, WebSocket-based SQL query interface that's optimized for the request/response patterns of AI agents and MCP tools.
  249. ### Installation
  250. **Quick Install (IBM i SSH Session):**
  251. ```bash
  252. # 1. Install Mapepire using yum
  253. yum install mapepire-server
  254. # 2. Install Service Commander (if not already installed)
  255. yum install service-commander
  256. # 3. Start Mapepire service
  257. sc start mapepire
  258. ```
  259. > [!NOTE]
  260. > **[πŸ“š Full Documentation: Mapepire System Administrator Guide β†’](https://mapepire-ibmi.github.io/guides/sysadmin/)**
  261. > [!IMPORTANT]
  262. > **Important Notes:**
  263. > - By default, Mapepire runs on port `8076`. You'll need this port number when configuring the `DB2i_PORT` variable in your `.env` file.
  264. > - Ensure your IBM i firewall allows inbound connections on port 8076
  265. > - For production deployments, configure SSL/TLS certificates (see official guide)
  266. ---
  267. ---
  268. ## License
  269. This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.