> ## Documentation Index
> Fetch the complete documentation index at: https://docs.db2i-mcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Client setup

> Configure Cursor, Claude Desktop, and Claude Code to start mcp-server-db2i, with npx or Docker.

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](docker.md#docker-secrets) for the most secure approach.

```json theme={null}
{
  "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:

```env theme={null}
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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

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

```bash theme={null}
export DB2I_HOSTNAME="your-host"
export DB2I_USERNAME="your-user"
export DB2I_PASSWORD="your-password"
```

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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](configuration.md#database-drivers).

### With Debug Logging

Enable debug logging for troubleshooting:

```json theme={null}
{
  "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

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

### Docker Issues

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

### Tool Errors

1. **Schema not found**: Verify schema name is correct (case-sensitive on IBM i)
2. **Table not found**: Ensure table exists and user has SELECT permission
3. **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:

```bash theme={null}
# If running detached
docker logs <container-id>

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

## Multiple Connections

You can configure multiple IBM i connections:

```json theme={null}
{
  "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

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

```bash theme={null}
export DB2I_HOSTNAME="your-host"
export DB2I_USERNAME="your-user"
export DB2I_PASSWORD="your-password"
```

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

```json theme={null}
{
  "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

```bash theme={null}
# Add server (credentials from shell environment)
claude mcp add --scope user db2i -- npx mcp-server-db2i

# Verify installation
claude mcp list
```


## Related topics

- [Quickstart](/quickstart.md)
- [Docker](/docker.md)
- [Configuration](/configuration.md)
- [HTTP transport](/http-transport.md)
- [Db2 for i MCP Server](/index.md)