---
title: "Docker MCP Servers: docker run and the MCP Toolkit"
url: "https://mcpshelf.co/guides/docker-mcp-servers"
description: "Run MCP servers in Docker two ways: as a docker run command in any app, or through the Docker MCP Toolkit and gateway. Flags, keys, folders and fixes."
updated: "2026-11-10"
site: "MCP Shelf"
---

# 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. **Find the image.** The server’s README or its page on the [shelf](https://mcpshelf.co/servers).
2. **Write the command.** `docker run -i --rm`, plus `-e` for keys.
3. **Restart the app.** Pull the image first so the start is quick.
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](https://mcpshelf.co/servers/postgres-mcp-pro) and [Terraform](https://mcpshelf.co/servers/terraform) both publish an image as their main install.

| Way | Best for | You need |
| --- | --- | --- |
| `docker run` in your app’s config | One or two servers, any app, any operating system | Docker Engine or Docker Desktop |
| Docker MCP Toolkit | Many servers managed in one place, with keys kept out of config files | Docker 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](https://mcpshelf.co/guides/claude-desktop), [Cursor](https://mcpshelf.co/guides/cursor), [Claude Code](https://mcpshelf.co/guides/claude-code), [JetBrains IDEs](https://mcpshelf.co/guides/jetbrains) 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"]
    }
  }
}
```

| Flag | What it does |
| --- | --- |
| `-i` | Keeps standard input open. The app talks to the server through it, so without `-i` the server exits at once and you see "Connection closed". |
| `--rm` | Deletes the container when the app closes it, so stopped containers do not pile up. |
| `-e NAME` | Passes one environment variable into the container. The value comes from the "env" block, so the key is not written in the args. |
| `-v` or `--mount` | Shares a folder from your computer with the server. Add `,readonly` (or `:ro`) when it only needs to read. |

> **Watch out:** Never add `-t`. A terminal attached to the container mixes control characters into the messages, and the app cannot read the server’s replies.

## 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. Update Docker Desktop to 4.62 or newer. Earlier versions have a different Toolkit screen.
2. Open Settings → Beta features, tick Enable Docker MCP Toolkit, and click Apply.
3. Open MCP Toolkit → Profiles and create a profile, such as "web-dev".
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. Open the Clients tab and click Connect next to your app. Docker writes the gateway into its config.
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"]
    }
  }
}
```

> **Watch out:** The gateway takes 15 to 25 seconds to start. If your app gives up after 10 seconds, raise its start-up timeout; in Codex that is `startup_timeout_sec` in config.toml.

## 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](https://mcpshelf.co/guides/test-an-mcp-server): `npx @modelcontextprotocol/inspector docker run -i --rm IMAGE`. Other messages are covered in [Fixing MCP server errors](https://mcpshelf.co/guides/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](https://mcpshelf.co/guides/check-an-mcp-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.

---

From [MCP Shelf](https://mcpshelf.co/): A short shelf of MCP servers that are worth installing. Index for agents: https://mcpshelf.co/llms.txt

