Db2i

CI npm version License: MIT MCP IBM i TypeScript Node.js Docker npm downloads PRs Welcome GitHub last commit

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.

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
• Dual Transport - Run stdio and HTTP simultaneously

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

Tool	Description
execute_query	Execute read-only SELECT queries
list_schemas	List schemas/libraries (with optional filter)
list_tables	List tables in a schema (with optional filter)
describe_table	Get detailed column information
list_views	List views in a schema (with optional filter)
list_indexes	List SQL indexes for a table
get_table_constraints	Get primary keys, foreign keys, unique constraints

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

Guide	Description
HTTP Transport	REST API with token authentication
Configuration	All environment variables and JDBC options
Security	Credentials, rate limiting, query validation
Client Setup	Cursor, Claude, Claude Code setup
Docker Guide	Container deployment
Development	Contributing and local setup

Compatibility

• IBM i V7R3 and later (V7R5 recommended)
• Node.js 20.6 or higher
• Java Runtime Environment (JRE) 11 or higher

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/sdk - Official TypeScript SDK