Docker & Podman - IBM i MCP Server

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

The commands below start a server for clients on the same machine. The server answers at http://localhost:3010/mcp and is not reachable from other hosts.

Docker
Podman

docker run -d \
  --name ibmi-mcp-server \
  -p 127.0.0.1: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 \
  -e MCP_ALLOW_UNAUTHENTICATED_HTTP=true \
  ghcr.io/ibm/ibmi-mcp-server:latest

podman run -d \
  --name ibmi-mcp-server \
  -p 127.0.0.1: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 \
  -e MCP_ALLOW_UNAUTHENTICATED_HTTP=true \
  ghcr.io/ibm/ibmi-mcp-server:latest

Verify the server is running:

curl http://localhost:3010/healthz

Two parts of this command control who can reach the server:

-p 127.0.0.1:3010:3010 publishes the port on the host’s loopback address only. -p 3010:3010 publishes it on every host interface, which makes an unauthenticated server that holds IBM i credentials reachable from the network.
MCP_ALLOW_UNAUTHENTICATED_HTTP=true accepts running without authentication. Without this variable or an MCP_AUTH_MODE setting, a container that holds IBM i credentials exits at startup. Network Exposure and Authentication describes both settings.

Replace the DB2i_* values with your actual IBM i credentials. Never commit credentials to source control.

Network Exposure and Authentication

The server holds the IBM i credentials it is started with. Any client that can send it a request can run SQL with those credentials. Two checks limit which clients can do so.

Host header validation

Every request must address the server as localhost, 127.0.0.1, or a name listed in MCP_ALLOWED_HOSTS. A request that uses any other name receives 403 Forbidden: Host not allowed. The check applies to every route, including /healthz. The check blocks DNS rebinding: a web page changes the DNS record for its own hostname to 127.0.0.1 after loading, then sends requests from the browser to the server on the visitor’s machine. Those requests carry the page’s hostname in the Host header and are rejected.

How the client addresses the server	Setting required
`http://localhost:3010/mcp` from the container host	None
Container name from another container, e.g. `http://ibmi-mcp-server:3010/mcp`	`MCP_ALLOWED_HOSTS=ibmi-mcp-server`
`http://host.docker.internal:3010/mcp`	`MCP_ALLOWED_HOSTS=host.docker.internal`
The host’s DNS name, e.g. `http://mcp.example.com:3010/mcp`	`MCP_ALLOWED_HOSTS=mcp.example.com`
A web page running in a browser	The page’s origin in `MCP_ALLOWED_ORIGINS`

MCP_ALLOWED_HOSTS accepts a comma-separated list. The 403 response body does not include the rejected name; the container log does.

Startup check for unauthenticated servers

The image sets MCP_HTTP_HOST=0.0.0.0, which published ports require. A server bound this way, holding IBM i credentials, with no authentication configured, is usable by anyone who can reach the port. The server refuses this configuration and exits with:

Refusing to start: unauthenticated HTTP transport on non-loopback bind 0.0.0.0 with IBM i credentials configured. Auth mode: none - authentication is disabled. Set MCP_AUTH_MODE, or MCP_HTTP_HOST=127.0.0.1, or MCP_ALLOW_UNAUTHENTICATED_HTTP=true.

“IBM i credentials” means DB2i_* variables or a tools YAML, since YAML sources: entries carry their own connection details. Set one of the following:

Setting	Effect
`MCP_AUTH_MODE=ibmi`	Clients authenticate with their own IBM i user and password. See IBM i Authentication.
`MCP_AUTH_MODE=oauth`	Clients present tokens from your OAuth provider.
`MCP_AUTH_MODE=jwt` and `MCP_AUTH_SECRET_KEY`	Clients present tokens you issue. `jwt` without a secret key is treated as no authentication.
`MCP_ALLOW_UNAUTHENTICATED_HTTP=true`	No authentication. Pair with `-p 127.0.0.1:3010:3010`, or use only on a network you trust.

Do not set MCP_HTTP_HOST=127.0.0.1 for a container. Docker and Podman forward published ports to the container’s network interface, not to its loopback address, so a server bound to 127.0.0.1 inside the container is unreachable from the host. Limit exposure with -p 127.0.0.1:3010:3010 instead. The repository’s .env.example sets MCP_HTTP_HOST=127.0.0.1; remove that line from any .env file passed to a container.

Available Images

Images are published to GitHub Container Registry on each release. Multi-architecture tags select the image for the host’s architecture; single-architecture tags pin one platform.

Tag	Platforms
`ghcr.io/ibm/ibmi-mcp-server:latest`	amd64, arm64, ppc64le
`ghcr.io/ibm/ibmi-mcp-server:v0.5.1`	amd64, arm64, ppc64le, pinned to a release
`ghcr.io/ibm/ibmi-mcp-server:amd64-v0.5.1`	x86-64 only
`ghcr.io/ibm/ibmi-mcp-server:arm64-v0.5.1`	ARM 64-bit only (Apple Silicon, ARM cloud instances)
`ghcr.io/ibm/ibmi-mcp-server:ppc64le-v0.5.1`	IBM Power (little-endian) only

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

Store the 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

# Authentication. Set MCP_AUTH_MODE, or accept an unauthenticated server.
MCP_ALLOW_UNAUTHENTICATED_HTTP=true

# Names other than localhost that clients use to reach the server.
# MCP_ALLOWED_HOSTS=ibmi-mcp-server

Then run with the env file:

Docker
Podman

docker run -d \
  --name ibmi-mcp-server \
  -p 127.0.0.1:3010:3010 \
  --env-file .env \
  ghcr.io/ibm/ibmi-mcp-server:latest

podman run -d \
  --name ibmi-mcp-server \
  -p 127.0.0.1:3010:3010 \
  --env-file .env \
  ghcr.io/ibm/ibmi-mcp-server:latest

Mounting Custom SQL Tools

To use your own YAML tool configurations, mount them into the container:

Docker
Podman

docker run -d \
  --name ibmi-mcp-server \
  -p 127.0.0.1:3010:3010 \
  --env-file .env \
  -v $(pwd)/tools:/usr/src/app/tools:ro \
  ghcr.io/ibm/ibmi-mcp-server:latest \
  npx ibmi-mcp-server --tools /usr/src/app/tools

podman run -d \
  --name ibmi-mcp-server \
  -p 127.0.0.1:3010:3010 \
  --env-file .env \
  -v $(pwd)/tools:/usr/src/app/tools:ro \
  ghcr.io/ibm/ibmi-mcp-server:latest \
  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.

A mounted tools directory counts as IBM i credentials for the startup check, because YAML sources: entries carry connection details. The .env file must set MCP_AUTH_MODE or MCP_ALLOW_UNAUTHENTICATED_HTTP=true.

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:latest
    ports:
      - "127.0.0.1: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

The .env file is the one from Using an Environment File. The healthcheck addresses the server as localhost and passes the Host check. Other services in the same Compose file reach the server as http://ibmi-mcp-server:3010/mcp; that name must be listed in MCP_ALLOWED_HOSTS. Start the service:

Docker
Podman

docker compose up -d

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

# Start the full stack
docker compose -f deployment/mcpgateway/docker-compose.yml up -d

Before starting the stack, edit .env:

Set DB2i_HOST, DB2i_USER, and DB2i_PASS.
Set MCP_ALLOWED_HOSTS=ibmi-mcp-server. The gateway addresses the server by container name.
Set MCP_AUTH_MODE, or set MCP_ALLOW_UNAUTHENTICATED_HTTP=true. The stack mounts the repository’s tools/ directory, which counts as IBM i credentials for the startup check.
Remove the MCP_HTTP_HOST=127.0.0.1 line. Compose passes .env to the container, and that value makes the server unreachable through the published port.

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
Podman

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

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

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

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

Stopping and Removing

Docker
Podman

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

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

The health endpoint is subject to the Host check. Both commands above address the server as localhost and pass. A probe that addresses the server by IP address, such as a Kubernetes probe using the pod IP, receives 403. Set a Host: localhost header on such probes; the repository’s OpenShift deployment manifest does this.

Building from Source

The image is built from packages/server/Dockerfile with the repository root as the build context. The root is required because the npm workspaces layout keeps a single package-lock.json there.

git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server
docker build -t ibmi-mcp-server:local -f packages/server/Dockerfile .

To run the local image, substitute ibmi-mcp-server:local for ghcr.io/ibm/ibmi-mcp-server:latest in any command on this page. The Dockerfile has three stages:

builder — installs all workspace dependencies and runs npm run build -w @ibm/ibmi-mcp-server
prod-deps — installs the server’s production dependencies only; the CLI workspace is excluded
runner — copies node_modules from prod-deps and the compiled packages/server/dist from builder, then starts node packages/server/dist/index.js

.dockerignore keeps node_modules/, dist/, .git/, .github/, .claude/, agents/, and .env files out of the build context.

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:

The log contains Refusing to start. See the next entry.
Missing or incorrect DB2i_* environment variables
Mapepire not running on the IBM i system
Network connectivity issues to IBM i host

Container exits with 'Refusing to start: unauthenticated HTTP transport'

The server holds IBM i credentials, has no authentication configured, and is bound to 0.0.0.0. It refuses this combination. Set MCP_AUTH_MODE, or set MCP_ALLOW_UNAUTHENTICATED_HTTP=true and publish the port with -p 127.0.0.1:3010:3010. See Network Exposure and Authentication.MCP_AUTH_MODE=jwt without MCP_AUTH_SECRET_KEY produces the same error, with Auth mode: jwt - MCP_AUTH_SECRET_KEY is unset in the message.

Requests return 403 Forbidden

Forbidden: Host not allowed. means the client addresses the server by a name that is not localhost and is not listed in MCP_ALLOWED_HOSTS. The container log records the rejected name. Add it to MCP_ALLOWED_HOSTS and restart the container.Forbidden: Origin not allowed. means the request came from a browser page whose origin is not listed in MCP_ALLOWED_ORIGINS. Add the origin, for example MCP_ALLOWED_ORIGINS=http://localhost:3000.

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 127.0.0.1:3011:3010 --env-file .env ghcr.io/ibm/ibmi-mcp-server:latest

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

​Quick Start

​Network Exposure and Authentication

​Host header validation

​Startup check for unauthenticated servers

​Available Images

​Using an Environment File

​Mounting Custom SQL Tools

​Docker Compose

​Standalone Server

​With MCP Context Forge Gateway

​Container Management

​Viewing Logs

​Stopping and Removing

​Health Checks

​Building from Source

​Troubleshooting

Quick Start

Network Exposure and Authentication

Host header validation

Startup check for unauthenticated servers

Available Images

Using an Environment File

Mounting Custom SQL Tools

Docker Compose

Standalone Server

With MCP Context Forge Gateway

Container Management

Viewing Logs

Stopping and Removing

Health Checks

Building from Source

Troubleshooting