Docker & Podman

Run the IBM i MCP Server using pre-built container images with Docker or Podman.

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:

Docker

# 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

Podman

# Pull the image (replace TAG with your architecture)
podman pull ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1

# Run the server
podman 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:

Architecture	Image Tag	Platform
x86-64	ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1	Standard servers, cloud VMs
ARM 64-bit	ghcr.io/ibm/ibmi-mcp-server:arm64-v0.3.1	Apple Silicon, ARM cloud instances
Power (LE)	ghcr.io/ibm/ibmi-mcp-server:ppc64le-v0.3.1	IBM 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

docker run -d \
  --name ibmi-mcp-server \
  -p 3010:3010 \
  --env-file .env \
  ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1

Podman

podman 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

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

Podman

podman 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

docker compose up -d

Podman

podman-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:

Service	Port	Description
MCP Context Forge	4444	Gateway with admin UI, tool federation, auth
IBM i MCP Server	3010	SQL tools MCP server
PostgreSQL	—	Gateway metadata storage (internal)
Redis	6379	Session cache
pgAdmin	5050	Database admin UI
Redis Insight	5540	Cache 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

Docker

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

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

Podman

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

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

Stopping and Removing

Docker

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

Podman

podman stop ibmi-mcp-server
podman 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

Container won't start

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

Cannot connect to IBM i from container

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.

Port conflicts

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

Permission denied on mounted volumes

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