mcp-server-db2i

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