home / mcp / ibm i mcp server

IBM i MCP Server

MCP server for IBM i systems

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ibm-ibmi-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@ibm/ibmi-mcp-server@latest",
        "--transport",
        "http",
        "--tools",
        "./tools/performance/performance.yaml"
      ],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "DB2i_USER": "your-username",
        "DB2i_IGNORE_UNAUTHORIZED": "true"
      }
    }
  }
}

You can run the IBM i MCP Server to let AI agents securely query Db2 for i, monitor system performance, and perform database operations through YAML-defined SQL tools and the Model Context Protocol (MCP). This guide walks you through practical usage, installation steps, and essential notes so you can start querying IBM i from AI agents and automation tools.

How to use

You will run the MCP Server locally or in a container and connect AI agents or Python clients to it. When connected, you can list the available SQL tools, and then execute those tools to retrieve system information, performance metrics, or perform database tasks on your IBM i system. Tools are defined in YAML configurations and are exercised by your MCP client through the server.

How to install

Prerequisites include a running Mapepire instance on IBM i (port 8076) and Node.js 18 or newer on the machine that will host the MCP Server.

Step by step starter setup using the local MCP Server runtime:

# 1. Clone the MCP Server repository

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

# 2. Configure your IBM i connection in a .env file
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 MCP Server with a predefined tool set
npx -y @ibm/ibmi-mcp-server@latest \
   --transport http \
   --tools ./tools/performance/performance.yaml

# To run in Docker instead, use the following command
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

Additional notes and setup tips

Mapepire is required to enable the MCP server to communicate with IBM i using a WebSocket-based SQL interface. Ensure you install Mapepire on IBM i, expose port 8076, and enable the necessary firewall rules for production use.

Key environment values you will provide in your .env include the IBM i host, user, password, and the Db2 for i port. You can tailor ignore-unauthorized behavior as needed during development.

If you choose to run the server in Docker, ensure you map your local tools directory and the .env file into the container, and provide the correct MCP_SERVER_CONFIG path inside the container.

Available tools

system_status

System status and performance metrics from IBM i, including CPU, memory, and active resources.