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 IMAGEas the command- Managed
- Docker MCP Toolkit in Docker Desktop 4.62+
- Common mistake
- Leaving out
-i, or adding-t
At a glance
- Step 1
1. Find the image
The server’s README or its page on the shelf.
- Step 2
2. Write the command
docker run -i --rm, plus-efor keys. - Step 3
3. Restart the app
Pull the image first so the start is quick.
- Step 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.
| 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, Cursor, Claude Code, JetBrains IDEs and every other app that runs local servers.
{
"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. |
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":
{
"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:
{
"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.
- Step 1: Update Docker Desktop to 4.62 or newer. Earlier versions have a different Toolkit screen.
- Step 2: Open Settings → Beta features, tick Enable Docker MCP Toolkit, and click Apply.
- Step 3: Open MCP Toolkit → Profiles and create a profile, such as "web-dev".
- 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.
- Step 5: Open the Clients tab and click Connect next to your app. Docker writes the gateway into its config.
- Step 6: Restart the app and check
MCP_DOCKERis listed. In Claude Code,claude mcp listshould show it as Connected.
For an app that is not on the Clients tab, add the gateway yourself. It is an ordinary local server:
{
"mcpServers": {
"MCP_DOCKER": {
"command": "docker",
"args": ["mcp", "gateway", "run", "--profile", "web-dev"]
}
}
}The Toolkit from the terminal
# 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-devdocker 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
dockeris not found, give the full path:/usr/local/bin/dockeron a Mac, orC:\Program Files\Docker\Docker\resources\bin\docker.exeon Windows. - On an Apple silicon Mac, an image built only for Intel needs
--platform linux/amd64and 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.
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