> ## Documentation Index
> Fetch the complete documentation index at: https://ibm-d95bab6e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tabs>
  <Tab title="Docker">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Podman">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

Verify the server is running:

```bash theme={null}
curl http://localhost:3010/healthz
```

<Warning>
  Replace the `DB2i_*` values with your actual IBM i credentials. Never commit credentials to source control.
</Warning>

***

## Available Images

Images are published to [GitHub Container Registry](https://github.com/IBM/ibmi-mcp-server/pkgs/container/ibmi-mcp-server) 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                  |

<Tip>
  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.
</Tip>

***

## Using an Environment File

For easier management, store your configuration in a `.env` file:

```ini theme={null}
# .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:

<Tabs>
  <Tab title="Docker">
    ```bash theme={null}
    docker run -d \
      --name ibmi-mcp-server \
      -p 3010:3010 \
      --env-file .env \
      ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1
    ```
  </Tab>

  <Tab title="Podman">
    ```bash theme={null}
    podman run -d \
      --name ibmi-mcp-server \
      -p 3010:3010 \
      --env-file .env \
      ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1
    ```
  </Tab>
</Tabs>

***

## Mounting Custom SQL Tools

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

<Tabs>
  <Tab title="Docker">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Podman">
    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

<Note>
  The `:ro` flag mounts the directory as read-only inside the container, which is a security best practice.
</Note>

***

## 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`:

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

<Tabs>
  <Tab title="Docker">
    ```bash theme={null}
    docker compose up -d
    ```
  </Tab>

  <Tab title="Podman">
    ```bash theme={null}
    podman-compose up -d
    ```
  </Tab>
</Tabs>

### With MCP Context Forge Gateway

The repository includes a full-stack Docker Compose configuration with [MCP Context Forge](https://github.com/IBM/mcp-context-forge) — a gateway that provides tool federation, authentication, rate limiting, and an admin UI.

```bash theme={null}
# 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                               |

<Info>
  The MCP Context Forge Gateway image must be built locally before starting the stack. See the [MCP Context Forge docs](https://ibm.github.io/mcp-context-forge/deployment/) for build instructions.
</Info>

***

## Container Management

### Viewing Logs

<Tabs>
  <Tab title="Docker">
    ```bash theme={null}
    # Follow logs
    docker logs -f ibmi-mcp-server

    # Last 100 lines
    docker logs --tail=100 ibmi-mcp-server
    ```
  </Tab>

  <Tab title="Podman">
    ```bash theme={null}
    # Follow logs
    podman logs -f ibmi-mcp-server

    # Last 100 lines
    podman logs --tail=100 ibmi-mcp-server
    ```
  </Tab>
</Tabs>

### Stopping and Removing

<Tabs>
  <Tab title="Docker">
    ```bash theme={null}
    docker stop ibmi-mcp-server
    docker rm ibmi-mcp-server
    ```
  </Tab>

  <Tab title="Podman">
    ```bash theme={null}
    podman stop ibmi-mcp-server
    podman rm ibmi-mcp-server
    ```
  </Tab>
</Tabs>

### Health Checks

The server exposes a health endpoint at `/healthz`:

```bash theme={null}
# 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:

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

<Note>
  The image runs as a non-root user (`appuser`) for security. Port 3010 is exposed by default.
</Note>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Container won't start">
    Check the container logs for error details:

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="Cannot connect to IBM i from container">
    Verify the container can reach your IBM i system:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="Port conflicts">
    If port 3010 is already in use, map to a different host port:

    ```bash theme={null}
    docker run -d -p 3011:3010 --env-file .env ghcr.io/ibm/ibmi-mcp-server:amd64-v0.3.1
    ```
  </Accordion>

  <Accordion title="Permission denied on mounted volumes">
    The container runs as a non-root user. Ensure mounted files are readable:

    ```bash theme={null}
    chmod -R 644 tools/
    ```

    On SELinux-enabled systems (RHEL/Fedora), add the `:z` flag:

    ```bash theme={null}
    -v $(pwd)/tools:/usr/src/app/tools:ro,z
    ```
  </Accordion>
</AccordionGroup>