IBM i MCP Server

<div align="center">  [](https://www.typescriptlang.org/) [](https://github.com/modelcontextprotocol/typescript-sdk) [](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx) [](https://opensource.org/licenses/Apache-2.0) [](https://github.com/IBM/ibmi-mcp-server.git) [](https://deepwiki.com/IBM/ibmi-mcp-server)  **MCP server for IBM i** </div> --- ## Overview 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.  > **How it works:** AI clients connect via MCP → Server executes YAML-defined SQL tools → Results stream back to the AI agent through Mapepire. > [!TIP] > **📚 [Official Documentation](https://ibm-d95bab6e.mintlify.app/) | ⚠️ Docs are under active development** > > 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! ### 📁 Repository Structure | Directory | Purpose | Documentation | |-----------|---------|---------------| | **`server/`** | MCP server implementation (TypeScript) | [Server README](./server/README.md) | | **`tools/`** | YAML-based SQL tool configurations | [Tools Guide](./tools/README.md) | | **`agents/`** | AI agent examples and integrations | [Agents Guide](./agents/README.md) | | **`client/`** | Python client examples for testing | [Client README](./client/README.md) | | **`deployment/`** | Docker, Podman, OpenShift configs | [Deployment Guide](./deployment/README.md) | ### 📖 Quick Navigation - [🚀 MCP Server](#-mcp-server) - Get started with the server - [🧩 SQL Tools](#-sql-tools) - Create custom SQL tools - [🤖 AI Agents](#-ai-agents) - Use agent frameworks - [🐍 Python Clients](#-python-clients) - Test with Python clients - [📦 Deployment](#-deployment) - Deploy to production - [📡 Setup Mapepire](#-setup-mapepire) - Install prerequisite --- ## 🚀 MCP Server The MCP Server enables AI agents to execute SQL queries on IBM i systems through YAML-defined SQL tools. ### Quick Start **Prerequisites:** - [Mapepire](#-setup-mapepire) running on IBM i (port 8076) - Node.js 18+ installed **Get Started:** 1. **Clone the repository:** ```bash git clone https://github.com/IBM/ibmi-mcp-server.git cd ibmi-mcp-server ``` 2. **Configure your IBM i connection:** ```bash 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:** ```bash 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. 4. **Verify it's running:** ```bash # 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](./server/README.md) > - [Server Configuration](./server/README.md#️-configuration) --- ## 🧩 SQL Tools YAML-based SQL tool configurations that define what queries AI agents can execute on your IBM i system. ### Quick Start Create a custom tool file `tools/my-tools.yaml`: ```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 ``` Run the server with your tools: ```bash npx -y @ibm/ibmi-mcp-server@latest --tools ./tools/my-tools.yaml --transport http ``` ### Available Tool Collections The `tools/` directory includes ready-to-use configurations: - **Performance Monitoring** - System status, active jobs, CPU/memory metrics - **Security & Audit** - User profiles, authorities, security events - **Job Management** - Active jobs, job queues, subsystems - **Storage & IFS** - Disk usage, IFS objects, save files - **Database** - Tables, indexes, constraints, statistics > [!NOTE] > **[📖 Full Documentation: Tools Guide →](https://ibm-d95bab6e.mintlify.app/sql-tools/overview)** > > **Additional links:** > - [Tools README](./tools/README.md) --- ## 🤖 AI Agents Pre-built AI agent examples using popular frameworks to interact with IBM i systems through the MCP Server. ### Available Agent Frameworks | Framework | Language | Use Case | Documentation | |-----------|----------|----------|---------------| | **Agno** | Python | Production-ready agents with built-in observability | [Agno README](./agents/frameworks/agno/README.md) | | **LangChain** | Python | Complex workflows and tool chaining | [LangChain README](./agents/frameworks/langchain/README.md) | | **Google ADK** | Python | Google AI ecosystem integration | [Google ADK README](./agents/frameworks/google_adk/README.md) | ### What Agents Can Do - **System Monitoring**: Real-time performance analysis and health checks - **Troubleshooting**: Diagnose issues using natural language queries - **Reporting**: Generate system reports and insights - **Automation**: Execute administrative tasks through conversation > [!NOTE] > **[📖 Full Documentation: Agents Guide →](https://ibm-d95bab6e.mintlify.app/agents/overview)** > > **Additional links:** > - [Agents README](./agents/README.md) --- ## 🐍 Python Clients Simple Python client examples for testing and interacting with the MCP Server. ```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()) ``` > [!NOTE] > **[📖 Full Documentation: Client README →](https://ibm-d95bab6e.mintlify.app/clients/overview)** > > **Additional links:** > - [Client README](./client/README.md) --- ## 📦 Deployment Production-ready deployment configurations for containerized environments. ### Deployment Options - **Docker & Podman** - Complete stack with MCP Context Forge Gateway - **OpenShift** - Kubernetes deployment with S2I builds - **Production Features** - HTTPS, authentication, monitoring, caching > [!NOTE] > **[📖 Full Documentation: Deployment Guide →](./deployment/README.md)** --- ## 📡 Setup Mapepire **Before you can use the ibmi-mcp-server, you must install and configure Mapepire on your IBM i system.** ### What is Mapepire? [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. ### Why Mapepire Enables AI and MCP Workloads Traditional IBM i database access methods (ODBC, JDBC) don't align well with modern AI and MCP architectures that require: - **Fast, lightweight connections**: AI agents make frequent, short-lived database queries - **WebSocket support**: Enables real-time, bidirectional communication for streaming results - **Modern JSON-based protocols**: Simplifies integration with TypeScript/JavaScript ecosystems - **Low-latency responses**: Essential for interactive AI conversations and tool executions 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. ### Installation **Quick Install (IBM i SSH Session):** ```bash # 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 ``` > [!NOTE] > **[📚 Full Documentation: Mapepire System Administrator Guide →](https://mapepire-ibmi.github.io/guides/sysadmin/)** > [!IMPORTANT] > **Important Notes:** > - By default, Mapepire runs on port `8076`. You'll need this port number when configuring the `DB2i_PORT` variable in your `.env` file. > - Ensure your IBM i firewall allows inbound connections on port 8076 > - For production deployments, configure SSL/TLS certificates (see official guide) --- --- ## 📜 License This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.