mcp-server-db2i

Node.js

A Model Context Protocol (MCP) server for IBM DB2 for i (DB2i). This server enables AI assistants like Claude and Cursor to query and inspect IBM i databases using the JT400 JDBC driver.

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

Architecture

AI clients connect to the MCP Server via stdio (IDEs) or HTTP (agents), which executes read-only queries against DB2 for i using the JT400 JDBC driver.

graph LR
    subgraph clients ["AI Clients"]
        claude("Claude")
        cursor("Cursor IDE")
        agents("Custom Agents")
    end

    subgraph server ["MCP Server"]
        stdio["stdio"]
        http["HTTP + Auth"]
        tools[["MCP Tools"]]
        jdbc["JT400 JDBC"]
    end

    subgraph ibmi ["IBM i"]
        db2[("DB2 for i")]
    end

    claude & cursor -->|MCP Protocol| stdio
    agents -->|REST API| http
    stdio & http --> tools
    tools --> jdbc
    jdbc -->|JDBC| db2

Features

• Read-only SQL queries - Execute SELECT statements safely with automatic result limiting
• 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 - REST API with token authentication for web/agent integration
• Current MCP spec - Speaks 2026-07-28 and still serves stateless 2025-era clients
• Dual Transport - Run stdio and HTTP simultaneously
• 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
• 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

Quick Start

Installation

npm install -g mcp-server-db2i

Or with Docker:

docker build -t mcp-server-db2i .

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": ["mcp-server-db2i"],
      "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.

Available Tools

Filter Syntax

The list tools support pattern matching:

• CUST - Contains "CUST"
• CUST* - Starts with "CUST"
• *LOG - Ends with "LOG"

Example Usage

Once connected, you can ask the AI assistant:

• "List all schemas that contain 'PROD'"
• "Show me the tables in schema MYLIB"
• "Describe the columns in MYLIB/CUSTOMERS"
• "What indexes exist on the ORDERS table?"
• "Run this query: SELECT * FROM MYLIB.CUSTOMERS WHERE STATUS = 'A'"

Documentation

Compatibility

• IBM i V7R3 and later (V7R5 recommended)
• validate_query and the execute_query parse check need QSYS2.PARSE_STATEMENT (IBM i 7.3 with Db2 PTF group SF99703 level 3, or 7.4 and later)
• get_related_objects needs IBM i 7.3 Technology Refresh 9, IBM i 7.4 Technology Refresh 3, or a later release
• Node.js 22 or higher
• Java Runtime Environment (JRE) 11 or higher
• MCP spec 2026-07-28, plus stateless clients from the 2025-era revisions (through 2025-11-25)

Related Projects

• IBM ibmi-mcp-server - IBM's official MCP server for IBM i systems. Offers YAML-based SQL tool definitions and AI agent frameworks. Requires Mapepire.

Contributing

Contributions are welcome! See the Development Guide for setup instructions.

License

MIT License - see LICENSE for details.

Acknowledgments

• node-jt400 - JT400 JDBC driver wrapper for Node.js
• Model Context Protocol - The protocol specification
• @modelcontextprotocol/server - Official TypeScript SDK (spec 2026-07-28, with stateless 2025-era clients)