Skip to main content
Run the IBM i MCP Server as a container using the official pre-built images from GitHub Container Registry. Supports amd64, arm64, and ppc64le architectures.

​
Quick Start

Pull and run the server in under a minute: 
# Pull the image (replace TAG with your architecture)
docker pull ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1

# Run the server
docker run -d \
  --name ibmi-mcp-server \
  -p 3010:3010 \
  -e DB2i_HOST=your-ibmi-host \
  -e DB2i_USER=your-username \
  -e DB2i_PASS=your-password \
  -e DB2i_PORT=8076 \
  -e DB2i_IGNORE_UNAUTHORIZED=true \
  -e MCP_TRANSPORT_TYPE=http \
  -e MCP_HTTP_PORT=3010 \
  ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1
Verify the server is running: 
curl http://localhost:3010/healthz
Replace the DB2i_* values with your actual IBM i credentials. Never commit credentials to source control.

​
Available Images

Images are published to GitHub Container Registry on each release:
ArchitectureImage TagPlatform
x86-64ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1Standard servers, cloud VMs
ARM 64-bitghcr.io/ibm/ibmi-mcp-server:arm64-v0.3.1Apple Silicon, ARM cloud instances
Power (LE)ghcr.io/ibm/ibmi-mcp-server:ppc64le-v0.3.1IBM Power Systems
Running on IBM Power Systems? Use the ppc64le image to run the MCP server natively on the same hardware as your IBM i partition — no emulation overhead.

​
Using an Environment File

For easier management, store your configuration in a .env file: 
# .env
DB2i_HOST=your-ibmi-host
DB2i_USER=your-username
DB2i_PASS=your-password
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_LOG_LEVEL=info
Then run with the env file: 
docker run -d \
  --name ibmi-mcp-server \
  -p 3010:3010 \
  --env-file .env \
  ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1

​
Mounting Custom SQL Tools

To use your own YAML tool configurations, mount them into the container: 
docker run -d \
  --name ibmi-mcp-server \
  -p 3010:3010 \
  --env-file .env \
  -v $(pwd)/tools:/usr/src/app/tools:ro \
  ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1 \
  npx ibmi-mcp-server --tools /usr/src/app/tools
The :ro flag mounts the directory as read-only inside the container, which is a security best practice.

​
Docker Compose

For a more complete setup, use Docker Compose to run the MCP server alongside supporting services.

​
Standalone Server

Create a docker-compose.yml: 
services:
  ibmi-mcp-server:
    image: ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1
    ports:
      - "3010:3010"
    env_file:
      - .env
    volumes:
      - ./tools:/usr/src/app/tools:ro
    command: ["npx", "ibmi-mcp-server", "--tools", "/usr/src/app/tools"]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3010/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped
Start the service: 
docker compose up -d

​
With MCP Context Forge Gateway

The repository includes a full-stack Docker Compose configuration with MCP Context Forge — a gateway that provides tool federation, authentication, rate limiting, and an admin UI. 
# Clone the repository
git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server

# Configure environment
cp .env.example .env
# Edit .env with your IBM i credentials

# Start the full stack
docker compose -f deployment/mcpgateway/docker-compose.yml up -d
This starts the following services:
ServicePortDescription
MCP Context Forge4444Gateway with admin UI, tool federation, auth
IBM i MCP Server3010SQL tools MCP server
PostgreSQL—Gateway metadata storage (internal)
Redis6379Session cache
pgAdmin5050Database admin UI
Redis Insight5540Cache admin UI
The MCP Context Forge Gateway image must be built locally before starting the stack. See the MCP Context Forge docs for build instructions.

​
Container Management

​
Viewing Logs

# Follow logs
docker logs -f ibmi-mcp-server

# Last 100 lines
docker logs --tail=100 ibmi-mcp-server

​
Stopping and Removing

docker stop ibmi-mcp-server
docker rm ibmi-mcp-server

​
Health Checks

The server exposes a health endpoint at /healthz: 
# From the host
curl http://localhost:3010/healthz

# From inside the container
docker exec ibmi-mcp-server curl http://localhost:3010/healthz

​
Building from Source

If you need to build the image locally instead of pulling from GHCR: 
git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server
docker build -t ibmi-mcp-server:local -f Dockerfile server/
The Dockerfile uses a multi-stage build:
  1. deps — Installs production Node.js dependencies
  2. builder — Installs all dependencies and compiles TypeScript
  3. runner — Final minimal image with only production deps and compiled output
The image runs as a non-root user (appuser) for security. Port 3010 is exposed by default.

​
Troubleshooting

Check the container logs for error details:
docker logs ibmi-mcp-server
Common causes:
  • Missing or incorrect DB2i_* environment variables
  • Mapepire not running on the IBM i system
  • Network connectivity issues to IBM i host
Verify the container can reach your IBM i system:
docker exec ibmi-mcp-server nc -zv your-ibmi-host 8076
If using Docker Desktop on macOS/Windows, ensure the IBM i host is reachable from within the VM.
If port 3010 is already in use, map to a different host port:
docker run -d -p 3011:3010 --env-file .env ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1
The container runs as a non-root user. Ensure mounted files are readable:
chmod -R 644 tools/
On SELinux-enabled systems (RHEL/Fedora), add the :z flag:
-v $(pwd)/tools:/usr/src/app/tools:ro,z