Client setup

This guide covers setting up mcp-server-db2i with MCP-compatible clients. The JSON configuration format is the same for all clients - only the file location differs.

Configuration Paths

Cursor

macOS/Linux: ~/.cursor/mcp.json
Windows: %USERPROFILE%\.cursor\mcp.json
Env var syntax: ${env:VAR_NAME}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

All platforms: ~/.claude.json
Project-specific: .mcp.json in project root
Env var syntax: ${VAR_NAME}
CLI: claude mcp add --scope user db2i -- npx mcp-server-db2i

Setup Options

Using Docker with env file (Recommended)

Store credentials in a separate .env file for security. For production deployments, see Docker Secrets for the most secure approach.

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

Create a .env file with your credentials:

DB2I_HOSTNAME=your-ibmi-host.com
DB2I_USERNAME=your-username
DB2I_PASSWORD=your-password

Using Docker with inline credentials

Security Warning: This stores credentials in plain text in your config file. Only use for local development or testing.

{
  "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-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 (Recommended for Cursor)

Use environment variable expansion to keep credentials out of config files.

Set credentials in your shell profile (~/.zshrc or ~/.bashrc):

export DB2I_HOSTNAME="your-host"
export DB2I_USERNAME="your-user"
export DB2I_PASSWORD="your-password"

Use ${env:VAR} syntax in your Cursor config:

{
  "mcpServers": {
    "db2i": {
      "command": "npx",
      "args": ["mcp-server-db2i"],
      "env": {
        "DB2I_HOSTNAME": "${env:DB2I_HOSTNAME}",
        "DB2I_USERNAME": "${env:DB2I_USERNAME}",
        "DB2I_PASSWORD": "${env:DB2I_PASSWORD}"
      }
    }
  }
}

Using npx with inline credentials

Security Warning: This stores credentials in plain text in your config file. Only use for local development or testing.

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

Local Development

For development or customization:

{
  "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"
      }
    }
  }
}

Configuration Options

With Default Schema

Set a default schema to avoid specifying it in every query:

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

With Custom Driver Options

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

DB2I_ODBC_OPTIONS applies to the default odbc image. With the jt400 image, pass JDBC properties in DB2I_JDBC_OPTIONS instead, for example naming=sql;date format=iso;errors=full. See Configuration.

With Debug Logging

Enable debug logging for troubleshooting:

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

Example Prompts

Once connected, you can ask the AI assistant:

Schema Exploration

“List all schemas that contain ‘PROD’”
“Show me all schemas on this system”
“What libraries are available?”

Table Discovery

“Show me the tables in schema MYLIB”
“List all tables that start with ‘CUST’”
“What tables are in the QGPL library?”

Column Information

“Describe the columns in MYLIB/CUSTOMERS”
“What’s the structure of the ORDERS table?”
“Show me the data types for MYLIB.INVENTORY”

Indexes and Constraints

“What indexes exist on the ORDERS table?”
“Show me the primary key for CUSTOMERS”
“List all foreign keys in the SALES schema”

SQL Queries

“Run this query: SELECT * FROM MYLIB.CUSTOMERS WHERE STATUS = ‘A’”
“Count the records in ORDERS where YEAR = 2024”
“Find customers with no orders in the last year”

Troubleshooting

Connection Issues

Check hostname resolution: Ensure the IBM i hostname is reachable
Verify credentials: Test with a known-good username/password
Check port: Default is 446, verify firewall allows access
Enable debug logging: Set LOG_LEVEL=debug

Docker Issues

Image not found: Build the image first with docker build -t mcp-server-db2i .
Permission denied: Ensure Docker daemon is running
Network issues: Check Docker network settings if IBM i is not reachable

Tool Errors

Schema not found: Verify schema name is correct (case-sensitive on IBM i)
Table not found: Ensure table exists and user has SELECT permission
Rate limit exceeded: Wait for the window to reset or adjust limits

Viewing Logs

For stdio transport, logs go to stderr. Docker logs can be viewed with:

# If running detached
docker logs <container-id>

# Real-time logs
docker logs -f <container-id>

Multiple Connections

You can configure multiple IBM i connections:

{
  "mcpServers": {
    "db2i-prod": {
      "command": "npx",
      "args": ["mcp-server-db2i"],
      "env": {
        "DB2I_HOSTNAME": "prod-ibmi.example.com",
        "DB2I_USERNAME": "produser",
        "DB2I_PASSWORD": "prodpass",
        "DB2I_SCHEMA": "PRODLIB"
      }
    },
    "db2i-dev": {
      "command": "npx",
      "args": ["mcp-server-db2i"],
      "env": {
        "DB2I_HOSTNAME": "dev-ibmi.example.com",
        "DB2I_USERNAME": "devuser",
        "DB2I_PASSWORD": "devpass",
        "DB2I_SCHEMA": "DEVLIB"
      }
    }
  }
}

Then specify which connection to use in your prompts: “Using db2i-prod, list all tables in PRODLIB”

Claude Code CLI

Claude Code supports environment variable expansion using ${VAR} syntax, which is the recommended secure approach.

Secure setup with environment variables

Set credentials in your shell profile (~/.zshrc or ~/.bashrc):

export DB2I_HOSTNAME="your-host"
export DB2I_USERNAME="your-user"
export DB2I_PASSWORD="your-password"

Add to ~/.claude.json with variable references:

{
  "mcpServers": {
    "db2i": {
      "command": "npx",
      "args": ["mcp-server-db2i"],
      "env": {
        "DB2I_HOSTNAME": "${DB2I_HOSTNAME}",
        "DB2I_USERNAME": "${DB2I_USERNAME}",
        "DB2I_PASSWORD": "${DB2I_PASSWORD}"
      }
    }
  }
}

This keeps credentials out of config files - Claude Code expands ${VAR} at runtime.

Using the CLI

# Add server (credentials from shell environment)
claude mcp add --scope user db2i -- npx mcp-server-db2i

# Verify installation
claude mcp list

Getting started

Reference

Deployment

Contributing

Configuration Paths

Cursor

Claude Desktop

Claude Code

Setup Options

Using Docker with env file (Recommended)

Using Docker with inline credentials

Using docker-compose

Using npx (Recommended for Cursor)

Using npx with inline credentials

Local Development

Configuration Options

With Default Schema

With Custom Driver Options

With Debug Logging

Example Prompts

Schema Exploration

Table Discovery

Column Information

Indexes and Constraints

SQL Queries

Troubleshooting

Connection Issues

Docker Issues

Tool Errors

Viewing Logs

Multiple Connections

Claude Code CLI

Secure setup with environment variables

Using the CLI

​Configuration Paths

​Cursor

​Claude Desktop

​Claude Code

​Setup Options

​Using Docker with env file (Recommended)

​Using Docker with inline credentials

​Using docker-compose

​Using npx (Recommended for Cursor)

​Using npx with inline credentials

​Local Development

​Configuration Options

​With Default Schema

​With Custom Driver Options

​With Debug Logging

​Example Prompts

​Schema Exploration

​Table Discovery

​Column Information

​Indexes and Constraints

​SQL Queries

​Troubleshooting

​Connection Issues

​Docker Issues

​Tool Errors

​Viewing Logs

​Multiple Connections

​Claude Code CLI

​Secure setup with environment variables

​Using the CLI

Configuration Paths

Cursor

Claude Desktop

Claude Code

Setup Options

Using Docker with env file (Recommended)

Using Docker with inline credentials

Using docker-compose

Using npx (Recommended for Cursor)

Using npx with inline credentials

Local Development

Configuration Options

With Default Schema

With Custom Driver Options

With Debug Logging

Example Prompts

Schema Exploration

Table Discovery

Column Information

Indexes and Constraints

SQL Queries

Troubleshooting

Connection Issues

Docker Issues

Tool Errors

Viewing Logs

Multiple Connections

Claude Code CLI

Secure setup with environment variables

Using the CLI