Skip to content
MCP Shelf

Build and run your own

Running MCP servers in Docker

By Sophie Filer · Updated 10 Nov 2026

Docker runs an MCP server in its own container, so it cannot see the rest of your computer unless you let it, and you need nothing installed but Docker. You can put a docker run command straight into your app, or let Docker Desktop’s MCP Toolkit manage a set of servers behind one gateway.

Simplest
docker run -i --rm IMAGE as the command
Managed
Docker MCP Toolkit in Docker Desktop 4.62+
Common mistake
Leaving out -i, or adding -t

At a glance

  1. 1. Find the image

    The server’s README or its page on the shelf.

  2. 2. Write the command

    docker run -i --rm, plus -e for keys.

  3. 3. Restart the app

    Pull the image first so the start is quick.

  4. 4. Use the tools

    The container stops when the app closes it.

Why run a server in Docker

  • Isolation: the server only sees the folders and keys you hand it, which matters for servers you have not written yourself.
  • No toolchains: you do not need the right version of Node.js, Python or Go, only Docker.
  • Repeatable: a pinned image tag runs the same way on every machine, so a team gets the same server.
  • Some servers ship this way first. Postgres MCP Pro and Terraform both publish an image as their main install.
WayBest forYou need
docker run in your app’s configOne or two servers, any app, any operating systemDocker Engine or Docker Desktop
Docker MCP ToolkitMany servers managed in one place, with keys kept out of config filesDocker Desktop 4.62 or newer

Way 1: a docker run command

Your app starts the container the same way it would start npx: docker is the command and the rest goes in "args". This works in Claude Desktop, Cursor, Claude Code, JetBrains IDEs and every other app that runs local servers.

Terraform’s official image, pinned to a version
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "hashicorp/terraform-mcp-server:1.4.1"]
    }
  }
}
FlagWhat it does
-iKeeps standard input open. The app talks to the server through it, so without -i the server exits at once and you see "Connection closed".
--rmDeletes the container when the app closes it, so stopped containers do not pile up.
-e NAMEPasses one environment variable into the container. The value comes from the "env" block, so the key is not written in the args.
-v or --mountShares a folder from your computer with the server. Add ,readonly (or :ro) when it only needs to read.

Pass keys and folders in

A container sees nothing from your computer by default: no environment variables, no files. Name each variable with -e and give it a value in "env":

A key, passed by name
{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "DATABASE_URI", "crystaldba/postgres-mcp", "--access-mode=restricted"],
      "env": { "DATABASE_URI": "postgresql://user:password@localhost:5432/dbname" }
    }
  }
}

Folders are shared with a mount. The server sees the folder at the path after dst=, so tell it that path, not your own:

Share one folder, read-only
{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/Users/you/Documents/notes,dst=/projects/notes,readonly",
        "mcp/filesystem", "/projects"
      ]
    }
  }
}

Inside a container, localhost means the container itself. To reach a database or API running on your own machine, use host.docker.internal (built into Docker Desktop; on Linux add --add-host=host.docker.internal:host-gateway). Some images, such as Postgres MCP Pro, rewrite localhost for you; their page on MCP Shelf says so.

Way 2: the Docker MCP Toolkit

The MCP Toolkit is a beta feature of Docker Desktop. You pick servers from Docker’s catalog into a profile, and one gateway (docker mcp gateway run) starts them as needed and presents them to your app as a single server called MCP_DOCKER. Keys and sign-ins are stored by Docker Desktop, not in your app’s config.

  1. Step 1: Update Docker Desktop to 4.62 or newer. Earlier versions have a different Toolkit screen.
  2. Step 2: Open Settings → Beta features, tick Enable Docker MCP Toolkit, and click Apply.
  3. Step 3: Open MCP Toolkit → Profiles and create a profile, such as "web-dev".
  4. Step 4: Open the Catalog tab, select the servers you want, and click Add to, choosing your profile. Fill in any server marked Configuration Required.
  5. Step 5: Open the Clients tab and click Connect next to your app. Docker writes the gateway into its config.
  6. Step 6: Restart the app and check MCP_DOCKER is listed. In Claude Code, claude mcp list should show it as Connected.

For an app that is not on the Clients tab, add the gateway yourself. It is an ordinary local server:

The gateway as a local server
{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "web-dev"]
    }
  }
}

The Toolkit from the terminal

Profiles, servers and clients with docker mcp
# make a profile and add two servers from Docker's catalog
docker mcp profile create --name web-dev
docker mcp profile server add web-dev \
  --server catalog://mcp/docker-mcp-catalog/github-official \
  --server catalog://mcp/docker-mcp-catalog/playwright

# see what is in it, then connect an app
docker mcp profile server ls --filter profile=web-dev
docker mcp client connect vscode --profile web-dev

docker mcp catalog server ls mcp/docker-mcp-catalog lists the IDs you can add. A profile can be saved into your repository with docker mcp profile export web-dev .docker/mcp-profile.json, and a teammate loads it with docker mcp profile import; keys are never included, so each person adds their own.

When a Docker server will not start

  • Is Docker running? If Docker Desktop is closed, every Docker server fails with "Cannot connect to the Docker daemon".
  • Pull the image first with docker pull IMAGE. A first start that downloads a large image can outlast the app’s start-up timeout.
  • Run the exact command in a terminal: docker run -i --rm IMAGE. It should sit there quietly waiting for input. An error printed here is the real problem.
  • Check for -i, and make sure there is no -t.
  • If the app says docker is not found, give the full path: /usr/local/bin/docker on a Mac, or C:\Program Files\Docker\Docker\resources\bin\docker.exe on Windows.
  • On an Apple silicon Mac, an image built only for Intel needs --platform linux/amd64 and runs slower.

Test any container with MCP Inspector: npx @modelcontextprotocol/inspector docker run -i --rm IMAGE. Other messages are covered in Fixing MCP server errors.

Questions

Is a Docker MCP server safer than one started with npx?

Usually, yes. The container cannot read your files or environment unless you mount or pass them in. It still has network access, and it can do anything the key you give it allows, so check the server all the same.

Do I need Docker Desktop?

Not for docker run commands: Docker Engine on Linux works too. The MCP Toolkit and the docker mcp commands need Docker Desktop 4.62 or newer.

Why does my server say "Connection closed" straight away?

Almost always a missing -i flag, so standard input closes and the server exits. Add -i after run, and remove any -t.

Can I run a remote MCP server in Docker?

Yes. A server that speaks HTTP can run with docker run -p 8000:8000 IMAGE, and your app connects to its address on localhost, such as http://localhost:8000/mcp (the README gives the port and path). For a stdio server, -i is all you need.

Plant Your First Pea

Every server on the shelf has a tab with the exact config for your app.

Browse servers

For bots & AI agents

Machine-readable versions of this guide and MCP Shelf. Fetch these instead of parsing this page.

This guide (.md)llms.txtllms-full.txtai.txtFull catalog (.md)API specMCP serverMCP manifestDeveloper docs