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.

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

Available Tools

Note: list_indexes and get_table_constraints query the QSYS2 SQL catalog views and only return SQL-defined objects. Legacy DDS Logical Files and Physical File constraints are not included. This is standard DB2 for i behavior.

Filter Syntax

The list tools support pattern matching:

• CUST - Contains "CUST"
• CUST* - Starts with "CUST"
• *LOG - Ends with "LOG"
• ORD*FILE - Starts with "ORD", ends with "FILE"

Installation

Prerequisites

• Node.js 18 or higher
• Java Runtime Environment (JRE) 11 or higher (for JDBC)
• Access to an IBM i system

Option 1: npm (recommended)

npm install -g mcp-server-db2i

Option 2: From source

git clone https://github.com/Strom-Capital/mcp-server-db2i.git
cd mcp-server-db2i
npm install
npm run build

Option 3: Docker

docker build -t mcp-server-db2i .

Configuration

Create a .env file or set environment variables:

# Required
DB2I_HOSTNAME=your-ibm-i-host.com
DB2I_USERNAME=your-username
DB2I_PASSWORD=your-password

# Optional - Database
DB2I_PORT=446                              # Default: 446
DB2I_DATABASE=*LOCAL                       # Default: *LOCAL
DB2I_SCHEMA=your-default-schema            # Default schema for all tools (can be overridden per-call)
DB2I_JDBC_OPTIONS=naming=system;date format=iso

# Optional - Logging
LOG_LEVEL=info                             # debug, info, warn, error, fatal (default: info)
NODE_ENV=production                        # production = JSON logs, development = pretty logs
LOG_PRETTY=true                            # Override: force pretty (true) or JSON (false) logs
LOG_COLORS=true                            # Override: force colors on/off (auto-detected by default)

# Optional - Rate Limiting
RATE_LIMIT_WINDOW_MS=900000                # Time window in ms (default: 900000 = 15 minutes)
RATE_LIMIT_MAX_REQUESTS=100                # Max requests per window (default: 100)
RATE_LIMIT_ENABLED=true                    # Set to 'false' to disable (default: true)

Environment Variables

JDBC Options

Common JDBC options for IBM i (JT400/JTOpen driver):

Example: naming=system;date format=iso;errors=full

Usage with Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json):

Using Docker (recommended)

{
  "mcpServers": {
    "db2i": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DB2I_HOSTNAME=your-host",
        "-e", "DB2I_USERNAME=your-user",
        "-e", "DB2I_PASSWORD=your-password",
        "mcp-server-db2i:latest"
      ]
    }
  }
}

Using Docker with env file

{
  "mcpServers": {
    "db2i": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/path/to/your/.env",
        "mcp-server-db2i:latest"
      ]
    }
  }
}

Using docker-compose

Create a .env file in the project root, then:

{
  "mcpServers": {
    "db2i": {
      "command": "docker-compose",
      "args": ["run", "--rm", "mcp-server-db2i"],
      "cwd": "/path/to/mcp-server-db2i"
    }
  }
}

The docker-compose.yml automatically reads from .env in the same directory.

Using npx (after npm install)

{
  "mcpServers": {
    "db2i": {
      "command": "npx",
      "args": ["mcp-server-db2i"],
      "env": {
        "DB2I_HOSTNAME": "your-host",
        "DB2I_USERNAME": "your-user",
        "DB2I_PASSWORD": "your-password"
      }
    }
  }
}

Local development

{
  "mcpServers": {
    "db2i": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-server-db2i/src/index.ts"],
      "env": {
        "DB2I_HOSTNAME": "your-host",
        "DB2I_USERNAME": "your-user",
        "DB2I_PASSWORD": "your-password"
      }
    }
  }
}

Example Queries

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'"

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run production build
npm start

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Lint and fix
npm run lint:fix

# Type check
npm run typecheck

Security

• Read-only access: Only SELECT statements are permitted
• No credentials in code: All sensitive data via environment variables
• Query validation: AST-based SQL parsing plus regex validation blocks dangerous operations
• Result limiting: Default limit of 1000 rows prevents large result sets
• Rate limiting: Configurable request throttling to prevent abuse (100 req/15 min default)
• Structured logging: Automatic redaction of sensitive fields like passwords

Compatibility

• IBM i V7R3 and later (V7R5 recommended)
• Works with any IBM i system accessible via JDBC over TCP/IP

Related Projects

• IBM ibmi-mcp-server - IBM's official MCP server for IBM i systems. Offers YAML-based SQL tool definitions, AI agent frameworks, and production deployment options. Requires Mapepire to be installed on your IBM i system, but if you can manage that prerequisite, it's worth checking out for more advanced use cases.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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
• IBM ibmi-mcp-server - SQL security validation patterns inspired by their approach to AST-based query validation