IBM Db2 for i

Db2 for i MCP Server

mcp-server-db2i is a Model Context Protocol (MCP) server for IBM Db2 for i (Db2i) on IBM i (AS/400). It enables AI assistants like Claude and Cursor to query and inspect IBM i databases through the IBM i Access ODBC driver, or optionally the JT400 JDBC driver or Mapepire over SSH.

Listed in the MCP Registry as io.github.Strom-Capital/mcp-server-db2i.

Website: db2i-mcp.com, with a blog that explains each release. Docs: docs.db2i-mcp.com.

Architecture

AI clients connect to the MCP Server in one of two ways. Local clients such as Claude Desktop, Claude Code and Cursor can start it as a process and talk over stdio. Remote clients connect over Streamable HTTP at /mcp, signing in with OAuth 2.1 (claude.ai custom connectors) or a bearer token (custom agents). Local clients can also use the HTTP endpoint. The server executes read-only queries against Db2 for i using the IBM i Access ODBC driver (default, no Java), the optional JT400 JDBC driver (DB2I_DRIVER=jt400), or Mapepire over SSH (DB2I_DRIVER=mapepire) for systems where only SSH is reachable. One server can reach several IBM i systems through connection profiles, each with its own driver.

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

Features

• Read-only SQL queries - Execute SELECT statements safely with automatic result limiting, and a query timeout that cancels runaway statements on the IBM i
• Schema inspection - List all schemas/libraries with optional filtering
• Table metadata - List tables, describe columns, view indexes and constraints
• View inspection - List and explore database views
• Secure by design - Only SELECT queries allowed, credentials via environment variables
• Docker support - Run as a container for easy deployment
• HTTP Transport - MCP over Streamable HTTP with token authentication for remote clients and agents
• OAuth for Remote Clients - Built-in OAuth 2.1 sign-in with the user's own IBM i profile, so claude.ai custom connectors can connect. The sign-in page can carry your company's name, logo, colors and language (Customize for your company)
• Current MCP spec - Speaks 2026-07-28 and still serves stateless 2025-era clients
• Dual Transport - Run stdio and HTTP simultaneously
• Multiple systems - Reach several IBM i systems from one server with DB2I_PROFILES, each with its own driver, credentials, and library allowlist. Tools take an optional system argument. See Multiple systems
• SSH-only systems - With DB2I_DRIVER=mapepire, reach an IBM i where only SSH is open. Mapepire starts inside the SSH session, with no server install and a host key check. See Using the Mapepire driver
• Tool selection - Enable or disable individual tools, e.g. a metadata-only mode without execute_query
• Business SQL tools - Load read-only ERP queries and table notes from YAML, and check the files with mcp-server-db2i validate-tools before the server starts. See Business SQL tools
• Server instructions - Send the rules no query may miss, such as which flag marks a deleted row, to the model at the start of every session. See Instructions
• Charts in the chat - Hosts that support MCP Apps show query results as a sortable grid under the tool call, with a chart one click away. When the user asks for a chart, or a YAML tool sets one, it opens on the chart. See Result view
• Compact responses - Compact JSON by default, or markdown tables to save tokens
• Statement checks and DDL - Validate object names, return the SQL that recreates an object, and list what depends on a table
• Catalog search and profiling - Find tables and columns across libraries, check journaling, and profile a table's row counts and value ranges
• Column masking - Redact sensitive columns, or show only their last four characters, in query results. See Column masking
• Query exports - Hand the user a CSV or Excel file of a query's results, as a file path over stdio or a short-lived download link over HTTP. The rows never pass through the model. See Query exports
• Audit log - Record every tool call and sign-in as one JSON line, with the SQL hashed by default. Optionally record the model's reason for each call (MCP_TOOL_INTENT). See Audit log
• Tool reload - Reload YAML tool files when they change, with MCP_CUSTOM_TOOLS_WATCH=true
• Resources and prompts - Read table columns and DDL as MCP resources, and start from prompts that explore a library, explain a table, or write a query. See Resources and prompts

Quick Start

Installation

npm install -g mcp-server-db2i

The default odbc driver needs unixODBC and the IBM i Access ODBC Driver on the machine. No Java is needed. The other drivers' packages are not installed by default, so add them next to the server:

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

With npx, pass them with -p, for example npx -y -p mcp-server-db2i@latest -p node-jt400 mcp-server-db2i. See Installing the jt400 and mapepire packages.

Or with 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)

Configuration

Create a .env file with your IBM i credentials:

DB2I_HOSTNAME=your-ibm-i-host.com

DB2I_USERNAME=your-username DB2I_PASSWORD=your-password DB2I_SCHEMA=your-default-schema # Optional

Client Setup

Add to your MCP client config (e.g., ~/.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}" } } } }

This uses environment variable expansion to keep credentials out of config files. Set the variables in your shell profile (~/.zshrc or ~/.bashrc).

See the Client Setup Guide for Cursor, Claude Desktop, Claude Code, and Docker setup options.

No MCP client? The example web app is a browser chat with result tables, exports and the business SQL tools. Users sign in with their IBM i user profile and bring their own model API key.

Available Tools

In hosts that support MCP Apps, results from execute_query, profile_table and business SQL tools open as a grid and a chart under the tool call. See Result view.

<source media="(prefers-color-scheme: dark)" srcset="docs/assets/result-view