MCP server and CLI for IBM i

---

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.

This repo also ships the ibmi CLI (@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.

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 | ⚠️ 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
packages/server/	MCP server implementation (TypeScript) — @ibm/ibmi-mcp-server on npm	Server README
packages/cli/	ibmi command-line interface — @ibm/ibmi-cli on npm, co-versioned with the server	CLI README
tools/	YAML-based SQL tool configurations	Tools Guide
agents/	AI agent examples and integrations	Agents Guide
client/	Python client examples for testing	Client README
deployment/	Docker, Podman, OpenShift configs	Deployment Guide
app/	Example Full stack Agent app (AgentOS)	App README

Quick Navigation

• MCP Server - Get started with the server
• IBM i CLI - Terminal-first SQL and tool execution
• SQL Tools - Create custom SQL tools
• AI Agents - Use agent frameworks
• Python Clients - Test with Python clients
• Deployment - Deploy to production
• 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 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 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 →

Next Steps:

• Create Custom Tools - Build your own SQL tools
• Connect AI Clients - Integrate with Claude, VSCode, Bob, etc.

Additional links:

• Server README
• Server Configuration
• Looking for the terminal CLI instead? Jump to IBM i CLI.

---

IBM i CLI

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.

Quick Start

# 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

When to use the CLI vs. the MCP Server

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.

Use the CLI when…	Use the MCP Server when…
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)
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
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 auth, rate limiting, structured telemetry, and session handling

See the CLI Agent Integration guide for concrete examples of wiring the ibmi CLI into local AI agents.

Note

📖 Full Documentation: CLI Guide →

Additional links:

• CLI README
• Getting Started
• Commands Reference
• Output Formats
• Agent Integration

---

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:

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:

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 →

Additional links:

• Tools README

---

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
LangChain	Python	Complex workflows and tool chaining	LangChain README
Google ADK	Python	Google AI ecosystem integration	Google ADK README

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 →

Additional links:

• Agents README

---

Python Clients

Simple Python client examples for testing and interacting with the MCP Server.

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 →

Additional links:

• Client README

---

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 →

---

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 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):

# 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 →

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 file for details.