Docker

This guide covers running mcp-server-db2i with Docker and docker-compose.

Quick Start

Build the Image

docker build -t mcp-server-db2i .

This builds the default odbc image with the IBM i Access ODBC Driver. IBM publishes no arm64 Linux build of that driver, so on an arm64 host such as an Apple Silicon Mac add --platform linux/amd64, or build the jt400 image instead. See Multi-Stage Build.

Run with Environment Variables

Security Warning: Passing credentials via -e flags exposes them in process lists (ps aux), docker inspect output, and shell history. Use --env-file for local testing and Docker secrets for production deployments.

# For quick local testing only - not recommended for production
docker run -i --rm \
  -e DB2I_HOSTNAME=your-host \
  -e DB2I_USERNAME=your-user \
  -e DB2I_PASSWORD=your-password \
  mcp-server-db2i

Run with env file (Recommended)

docker run -i --rm \
  --env-file .env \
  mcp-server-db2i

Docker Compose

Basic Setup

Create a .env file:

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

Run with docker-compose:

docker-compose run --rm mcp-server-db2i

HTTP Transport

To expose the HTTP API, uncomment the ports section in docker-compose.yml:

services:
  mcp-server-db2i:
    # ...
    ports:
      - "${MCP_HTTP_PORT:-3000}:${MCP_HTTP_PORT:-3000}"
    environment:
      - MCP_TRANSPORT=http
      # ...

Then run:

docker-compose up -d

Docker Secrets

For production deployments, use Docker secrets instead of environment variables.

1. Create Secret Files

mkdir -p ./secrets

# Securely prompt for username (doesn't leak to shell history)
read -p "Enter Db2i username: " username
echo "$username" > ./secrets/db2i_username.txt

# Securely prompt for password (hidden input)
read -s -p "Enter Db2i password: " password
echo
echo "$password" > ./secrets/db2i_password.txt

chmod 600 ./secrets/*.txt

Security Note: Avoid using echo "password" > file directly, as it may be logged in shell history. The read -s command hides input from the terminal.

2. Update docker-compose.yml

services:
  mcp-server-db2i:
    build: .
    container_name: mcp-server-db2i
    stdin_open: true
    tty: true
    environment:
      - DB2I_HOSTNAME=${DB2I_HOSTNAME}
      - DB2I_USERNAME_FILE=/run/secrets/db2i_username
      - DB2I_PASSWORD_FILE=/run/secrets/db2i_password
    secrets:
      - db2i_username
      - db2i_password

secrets:
  db2i_username:
    file: ./secrets/db2i_username.txt
  db2i_password:
    file: ./secrets/db2i_password.txt

3. Run

docker-compose up -d

TLS with Docker

Using Built-in TLS

Mount your certificates:

services:
  mcp-server-db2i:
    # ...
    volumes:
      - ./certs:/certs:ro
    environment:
      - MCP_TLS_ENABLED=true
      - MCP_TLS_CERT_PATH=/certs/server.crt
      - MCP_TLS_KEY_PATH=/certs/server.key

Generate self-signed certificates (for testing):

mkdir -p ./certs
openssl req -x509 -newkey rsa:4096 -keyout certs/server.key -out certs/server.crt -days 365 -nodes -subj "/CN=localhost"

Using Reverse Proxy

For production, use a reverse proxy like nginx or Traefik for TLS termination:

services:
  mcp-server-db2i:
    # ...
    environment:
      # 0.0.0.0 so the proxy container can reach this process. 127.0.0.1 is only this container's loopback.
      - MCP_HTTP_HOST=0.0.0.0
      - MCP_HTTP_PORT=3000
      # Name clients send in Host. Loopback alone is not enough once a proxy forwards a public hostname.
      - MCP_ALLOWED_HOSTS=db2i.example.com

  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - mcp-server-db2i

Environment Variables

All environment variables can be set in docker-compose.yml or via .env file:

environment:
  # Database connection
  - DB2I_HOSTNAME=${DB2I_HOSTNAME}
  - DB2I_USERNAME=${DB2I_USERNAME}
  - DB2I_PASSWORD=${DB2I_PASSWORD}
  - DB2I_SCHEMA=${DB2I_SCHEMA:-}
  # DB2I_DRIVER is set by the image target (odbc or jt400)
  - DB2I_JDBC_OPTIONS=${DB2I_JDBC_OPTIONS:-}
  - DB2I_ODBC_OPTIONS=${DB2I_ODBC_OPTIONS:-}
  
  # Transport settings
  - MCP_TRANSPORT=${MCP_TRANSPORT:-stdio}
  - MCP_HTTP_PORT=${MCP_HTTP_PORT:-3000}
  - MCP_HTTP_HOST=${MCP_HTTP_HOST:-127.0.0.1}
  - MCP_ALLOWED_HOSTS=${MCP_ALLOWED_HOSTS:-}
  - MCP_SESSION_MODE=${MCP_SESSION_MODE:-stateless}
  - MCP_TOKEN_EXPIRY=${MCP_TOKEN_EXPIRY:-3600}
  - MCP_MAX_SESSIONS=${MCP_MAX_SESSIONS:-100}
  - MCP_POOL_IDLE_TIMEOUT=${MCP_POOL_IDLE_TIMEOUT:-600}
  
  # TLS settings
  - MCP_TLS_ENABLED=${MCP_TLS_ENABLED:-false}
  - MCP_TLS_CERT_PATH=${MCP_TLS_CERT_PATH:-}
  - MCP_TLS_KEY_PATH=${MCP_TLS_KEY_PATH:-}
  
  # Rate limiting
  - RATE_LIMIT_WINDOW_MS=${RATE_LIMIT_WINDOW_MS:-900000}
  - RATE_LIMIT_MAX_REQUESTS=${RATE_LIMIT_MAX_REQUESTS:-100}
  - RATE_LIMIT_ENABLED=${RATE_LIMIT_ENABLED:-true}
  - AUTH_RATE_LIMIT_MAX_ATTEMPTS=${AUTH_RATE_LIMIT_MAX_ATTEMPTS:-5}
  - AUTH_RATE_LIMIT_WINDOW_MS=${AUTH_RATE_LIMIT_WINDOW_MS:-60000}
  - OAUTH_RATE_LIMIT_MAX_REQUESTS=${OAUTH_RATE_LIMIT_MAX_REQUESTS:-120}
  - OAUTH_RATE_LIMIT_WINDOW_MS=${OAUTH_RATE_LIMIT_WINDOW_MS:-60000}
  
  # Query limits
  - QUERY_DEFAULT_LIMIT=${QUERY_DEFAULT_LIMIT:-1000}
  - QUERY_MAX_LIMIT=${QUERY_MAX_LIMIT:-10000}
  - QUERY_TIMEOUT=${QUERY_TIMEOUT:-}
  - QUERY_ALLOWED_SCHEMAS=${QUERY_ALLOWED_SCHEMAS:-}
  - QUERY_PARSE_CHECK=${QUERY_PARSE_CHECK:-}
  - QUERY_MAX_LENGTH=${QUERY_MAX_LENGTH:-}
  
  # Query exports (export_query)
  - EXPORT_ENABLED=${EXPORT_ENABLED:-}
  - EXPORT_DIR=${EXPORT_DIR:-/data/exports}
  - MCP_PUBLIC_URL=${MCP_PUBLIC_URL:-}
  
  # Tool selection and response format
  - MCP_TOOLS_ENABLED=${MCP_TOOLS_ENABLED:-}
  - MCP_TOOLS_DISABLED=${MCP_TOOLS_DISABLED:-}
  - MCP_CUSTOM_TOOLS=${MCP_CUSTOM_TOOLS:-}
  - MCP_RESPONSE_FORMAT=${MCP_RESPONSE_FORMAT:-json}
  
  # Logging
  - LOG_LEVEL=${LOG_LEVEL:-info}

Business SQL tools

Mount a directory of YAML tool files and point MCP_CUSTOM_TOOLS at it. The example pack in examples/erp-tools uses placeholder names such as MYLIB.ORDERHDR. Edit those names before relying on the tools.

services:
  mcp-server-db2i:
    environment:
      - MCP_CUSTOM_TOOLS=/tools
      - QUERY_ALLOWED_SCHEMAS=MYLIB
    volumes:
      - ./examples/erp-tools:/tools:ro

The server reads the files at startup. A statement that is not a query, or that names a library outside QUERY_ALLOWED_SCHEMAS, stops the container. See Business SQL tools.

Query exports

The image has an empty /data/exports directory owned by mcpuser with mode 0700. Point EXPORT_DIR at it and mount a named volume there, which takes the same owner:

services:
  mcp-server-db2i:
    environment:
      - EXPORT_ENABLED=true
      - EXPORT_DIR=/data/exports
      # HTTP: download links are <MCP_PUBLIC_URL>/exports/<id>
      - MCP_PUBLIC_URL=https://mcp.example.com
    volumes:
      - exports:/data/exports

volumes:
  exports:

Over HTTP, users download through the link and never see the path. Over stdio the result is a path inside the container, which is only useful on the host through a bind mount: mount a host directory at /data/exports and make it writable by the container’s mcpuser. See Query exports.

Multi-Stage Build

The Dockerfile uses a multi-stage build with two runtime targets:

Builder stage: Compiles TypeScript to JavaScript, then installs the production packages for each target. Both include @ibm/mapepire-js and ssh2; only the jt400 target includes node-jt400
odbc target (default): unixODBC and the IBM i Access ODBC Driver from IBM’s apt repository, no Java. Sets DB2I_DRIVER=odbc.
jt400 target: OpenJDK 17 JRE and node-jt400 for the JT400 JDBC driver. Sets DB2I_DRIVER=jt400.

# ODBC image (default), no JDK or JRE
docker build -t mcp-server-db2i .
docker run --rm -i --env-file .env -e DB2I_ODBC_OPTIONS="SSL=1" mcp-server-db2i

# JDBC image
docker build --target jt400 -t mcp-server-db2i:jt400 .

IBM publishes the ODBC driver package for amd64 and ppc64el, and its apt repository also carries older i386 builds (see Installing the IBM i Access ODBC Driver). There is no arm64 build, so in practice the ODBC image is an amd64 image. On an arm64 host such as an Apple Silicon Mac, build and run it under emulation with --platform linux/amd64; the build fails early with a message otherwise. The jt400 image builds natively on arm64.

docker build --platform linux/amd64 -t mcp-server-db2i .

Either image can run the mapepire driver, because it needs nothing native. Override the driver and pin the host key, since the container has no known_hosts. Alternatively, mount a known_hosts file and set knownHostsFile to its path.

docker run --rm -i --env-file .env -e DB2I_DRIVER=mapepire \
  -e DB2I_MAPEPIRE_OPTIONS="hostKey=SHA256:abc...xyz" mcp-server-db2i:jt400

To tell images apart in the audit log between releases, pass the git commit as MCP_BUILD_ID. Every audit line then records it as build, next to serverVersion:

docker build --build-arg MCP_BUILD_ID=$(git rev-parse --short HEAD) -t mcp-server-db2i .

The bundled docker-compose.yml builds the ODBC image with platform: linux/amd64. To use the JDBC image, set target: jt400 under build and remove the platform line. Both images:

Use node:22-bookworm-slim. Bookworm is pinned so OpenJDK 17 stays available for the jt400 target. Debian trixie does not package it.
Run as non-root user (mcpuser)
Include only production dependencies
Default MCP_SESSION_MODE to stateless, matching the server. stateful is deprecated.

The odbc image installs ibm-iaccess from public.dhe.ibm.com at build time, so the build needs network access to that host. See Database Drivers for the ODBC keywords.

Health Checks

For HTTP transport, add a health check:

services:
  mcp-server-db2i:
    # ...
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Note: The image is Debian slim and does not include curl or wget. The check uses Node’s built-in fetch.

Resource Limits

Set resource limits for production:

services:
  mcp-server-db2i:
    # ...
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

Logging

View Logs

# Follow logs
docker-compose logs -f mcp-server-db2i

# Last 100 lines
docker-compose logs --tail=100 mcp-server-db2i

Log Configuration

For production, use JSON logging:

environment:
  - NODE_ENV=production
  - LOG_LEVEL=info

Log Drivers

Configure Docker log drivers for centralized logging:

services:
  mcp-server-db2i:
    # ...
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Networking

Bridge Network (default)

services:
  mcp-server-db2i:
    # ...
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Host Network

For better performance (Linux only):

services:
  mcp-server-db2i:
    # ...
    network_mode: host

Example: Complete Production Setup

version: '3.8'

services:
  mcp-server-db2i:
    build: .
    container_name: mcp-server-db2i
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - DB2I_HOSTNAME=${DB2I_HOSTNAME}
      - DB2I_USERNAME_FILE=/run/secrets/db2i_username
      - DB2I_PASSWORD_FILE=/run/secrets/db2i_password
      - DB2I_SCHEMA=${DB2I_SCHEMA}
      - MCP_TRANSPORT=http
      - MCP_HTTP_HOST=0.0.0.0
      - MCP_ALLOWED_HOSTS=${MCP_ALLOWED_HOSTS:-}
      - MCP_TLS_ENABLED=true
      - MCP_TLS_CERT_PATH=/certs/server.crt
      - MCP_TLS_KEY_PATH=/certs/server.key
      - NODE_ENV=production
      - LOG_LEVEL=info
    secrets:
      - db2i_username
      - db2i_password
    volumes:
      - ./certs:/certs:ro
    healthcheck:
      test: ["CMD", "node", "-e", "process.env.NODE_TLS_REJECT_UNAUTHORIZED='0'; fetch('https://127.0.0.1:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

secrets:
  db2i_username:
    file: ./secrets/db2i_username.txt
  db2i_password:
    file: ./secrets/db2i_password.txt

Troubleshooting

Container Won’t Start

Check logs: docker-compose logs mcp-server-db2i
Verify environment variables are set
Ensure IBM i is reachable from container

Connection Refused

Check that the container can reach the IBM i ports your driver uses: 449, 8476 and 8471 (9476 and 9471 with TLS) for odbc and jt400, or SSH (port 22) for mapepire. Port 446 is not used
Verify hostname resolves correctly
Check firewall rules

Permission Denied

Ensure secret files have correct permissions
Check volume mount permissions
Verify non-root user has access

Out of Memory

Increase memory limits
Reduce QUERY_MAX_LIMIT
Lower MCP_MAX_SESSIONS

Getting started

Reference

Deployment

Contributing

Quick Start

Build the Image

Run with Environment Variables

Run with env file (Recommended)

Docker Compose

Basic Setup

HTTP Transport

Docker Secrets

1. Create Secret Files

2. Update docker-compose.yml

3. Run

TLS with Docker

Using Built-in TLS

Using Reverse Proxy

Environment Variables

Business SQL tools

Query exports

Multi-Stage Build

Health Checks

Resource Limits

Logging

View Logs

Log Configuration

Log Drivers

Networking

Bridge Network (default)

Host Network

Example: Complete Production Setup

Troubleshooting

Container Won’t Start

Connection Refused

Permission Denied

Out of Memory

​Quick Start

​Build the Image

​Run with Environment Variables

​Run with env file (Recommended)

​Docker Compose

​Basic Setup

​HTTP Transport

​Docker Secrets

​1. Create Secret Files

​2. Update docker-compose.yml

​3. Run

​TLS with Docker

​Using Built-in TLS

​Using Reverse Proxy

​Environment Variables

​Business SQL tools

​Query exports

​Multi-Stage Build

​Health Checks

​Resource Limits

​Logging

​View Logs

​Log Configuration

​Log Drivers

​Networking

​Bridge Network (default)

​Host Network

​Example: Complete Production Setup

​Troubleshooting

​Container Won’t Start

​Connection Refused

​Permission Denied

​Out of Memory

Quick Start

Build the Image

Run with Environment Variables

Run with env file (Recommended)

Docker Compose

Basic Setup

HTTP Transport

Docker Secrets

1. Create Secret Files

2. Update docker-compose.yml

3. Run

TLS with Docker

Using Built-in TLS

Using Reverse Proxy

Environment Variables

Business SQL tools

Query exports

Multi-Stage Build

Health Checks

Resource Limits

Logging

View Logs

Log Configuration

Log Drivers

Networking

Bridge Network (default)

Host Network

Example: Complete Production Setup

Troubleshooting

Container Won’t Start

Connection Refused

Permission Denied

Out of Memory