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