Docker Mcp Linux

Docker MCP Gateway on Linux

This guide covers installing and running the Docker MCP Gateway on Linux without Docker Desktop. The gateway is the same technology that powers the MCP Toolkit in Docker Desktop, but it runs entirely from the open-source docker/mcp-gateway CLI plugin.

Prerequisites

Install Docker Engine on Ubuntu/Debian:

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# Log out and back in so group membership takes effect

Installation

1. Clone and Build the CLI Plugin

git clone https://github.com/docker/mcp-gateway.git
cd mcp-gateway

# Create the Docker CLI plugins directory
mkdir -p "$HOME/.docker/cli-plugins/"

# Build and install
make docker-mcp

Verify the installation:

docker mcp --help

2. Set the Required Environment Variable

On Linux with Docker CE, the gateway must be told it is not running inside Docker Desktop. Without this, commands fail with "Docker Desktop is not running" even when the daemon is active.

export DOCKER_MCP_IN_CONTAINER=1

Persist it across sessions:

echo 'export DOCKER_MCP_IN_CONTAINER=1' >> ~/.bashrc
source ~/.bashrc

3. Enable Profiles

Profiles are enabled automatically in Docker Desktop. On Linux CE you must enable the feature manually once:

docker mcp feature enable profiles

Catalog Setup

The Docker MCP Catalog is a curated OCI image of pre-packaged MCP server definitions hosted on Docker Hub.

Pull the Default Catalog

docker mcp catalog pull mcp/docker-mcp-catalog

Browse Available Servers

docker mcp catalog server ls mcp/docker-mcp-catalog

Profile Setup

A profile groups one or more MCP servers together. The gateway runs a single profile at a time and exposes all the tools from its servers to the connected AI client.

Create a Profile

docker mcp profile create --name my-profile \
  --server catalog://mcp/docker-mcp-catalog/github

To include multiple servers in one profile:

docker mcp profile create --name my-profile \
  --server catalog://mcp/docker-mcp-catalog/github \
  --server catalog://mcp/docker-mcp-catalog/grafana \
  --server catalog://mcp/docker-mcp-catalog/atlassian

List Profiles

docker mcp profile list

Configure a Server in a Profile

Some MCP servers require API keys or tokens. Set them as profile config values:

docker mcp profile config my-profile --set github.token=ghp_...
docker mcp profile config my-profile --set grafana.url=http://localhost:3000
docker mcp profile config my-profile --set grafana.token=glsa_...

Manage Secrets (Recommended)

For credentials, use the secrets store instead of plain config so values are not stored in plaintext:

docker mcp secret set github.token
# Prompts for value interactively

Running the Gateway

stdio Mode (for use with opencode, Claude, VS Code, etc.)

The AI client spawns the gateway as a subprocess. This is the standard mode for opencode and most MCP clients.

docker mcp gateway run --profile my-profile

HTTP Streaming Mode (for multi-client or remote use)

docker mcp gateway run --profile my-profile --port 8080 --transport streaming

Connecting to opencode

Add the gateway as an MCP server in your opencode configuration at ~/.config/opencode/config.json:

{
  "mcp": {
    "docker": {
      "type": "local",
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "my-profile"],
      "env": {
        "DOCKER_MCP_IN_CONTAINER": "1"
      }
    }
  }
}

The DOCKER_MCP_IN_CONTAINER env var is set inline here as a safety net, even if it is already in your shell profile.

Verify Tools Are Visible

After opening opencode, confirm the tools loaded correctly:

docker mcp tools ls --profile my-profile
docker mcp tools count

Connecting to Other Clients

The gateway also supports Claude Desktop, VS Code, and Cursor.

# Connect to Claude Desktop
docker mcp client connect claude --profile my-profile

# Connect to VS Code
docker mcp client connect vscode --profile my-profile

# Connect to Cursor
docker mcp client connect cursor --profile my-profile --global

Tool Management

List All Available Tools

docker mcp tools ls

Inspect a Specific Tool

docker mcp tools inspect search_cves

Call a Tool Directly (for testing)

docker mcp tools call search_cves '{"query": "remote code execution", "top_k": 5}'

Restrict Which Tools Are Exposed

# Enable only specific tools from a server
docker mcp profile tools my-profile --enable github.create_issue --enable github.list_repos

# Disable a tool
docker mcp profile tools my-profile --disable github.search_code

# Disable all tools for a server, then selectively enable
docker mcp profile tools my-profile --disable-all grafana
docker mcp profile tools my-profile --enable grafana.search_dashboards

Zagros MCP Server on Linux

The zagros-mcp server in this project uses the same Docker MCP mechanism. To register it manually on Linux instead of using register.ps1:

1. Build the Image

docker build -t zagros-mcp:0.1.0 .

2. Create a Local Server Definition

Create docker/server-linux.yaml:

name: zagros
description: Zagros search and retrieval tools
image: zagros-mcp:0.1.0
environment:
  HELIX_URL: http://host.docker.internal:47474
allowHosts:
  - raw.githubusercontent.com:443
volumes:
  - zagros-data:/data

3. Add to a Profile

docker mcp profile create --name zagros-profile \
  --server file://./docker/server-linux.yaml

4. Run the Gateway

DOCKER_MCP_IN_CONTAINER=1 docker mcp gateway run --profile zagros-profile

Troubleshooting

Docker Desktop is not running

Error: Docker Desktop is not running

Fix: Set DOCKER_MCP_IN_CONTAINER=1 in your environment.

permission denied on /var/run/docker.sock

permission denied while trying to connect to the Docker daemon socket

Fix: Add your user to the docker group and re-login:

sudo usermod -aG docker $USER

docker mcp command not found

The CLI plugin binary must be in ~/.docker/cli-plugins/. Verify:

ls -la ~/.docker/cli-plugins/docker-mcp

If missing, rebuild:

cd mcp-gateway && make docker-mcp

Container cannot reach HelixDB

Inside a Docker container, localhost refers to the container itself, not the host. Use the Docker-provided host alias instead:

environment:
  HELIX_URL: http://host.docker.internal:47474

On some Linux Docker Engine versions, host.docker.internal is not automatically available. Add it explicitly when running the container:

docker run --add-host=host.docker.internal:host-gateway ...

Gateway exits immediately with no output

Run with verbose logging to diagnose:

DOCKER_MCP_IN_CONTAINER=1 docker mcp gateway run --profile my-profile --log-level debug

Reference

See Also

• MCP.md — Zagros MCP server tool reference
• CONFIGURATION.md — HelixDB and environment setup
• docker/mcp-gateway on GitHub — upstream source