Deploying MCP Servers with Docker: The Complete Guide

Docker is the most common deployment target for MCP servers in team and production environments. Containerizing your MCP server gives you consistent environments, easy scaling, and clean isolation from the host system — critical when your server has access to sensitive tools and data.

This guide walks through everything from a basic Dockerfile to production-ready multi-service deployments with Docker Compose.

Why Docker for MCP Servers?

MCP servers have specific reasons to containerize beyond the usual "it works on my machine" benefits:

• Security isolation — MCP servers often have elevated access (filesystem, database, APIs). Docker namespacing and capabilities restrictions limit blast radius if a server is compromised.
• Consistent tool versions — Node.js and Python MCP servers depend on specific SDK versions. Docker locks this in for every team member and deployment environment.
• Multi-server orchestration — Running 5+ MCP servers? Docker Compose manages them as a unit with shared networking and volume mounts.
• Resource limits — Prevent a runaway MCP process from consuming host resources with container CPU/memory limits.

Basic Dockerfile for a Node.js MCP Server

Most official MCP servers are Node.js packages. Here's a production-ready Dockerfile for a typical Node.js MCP server:

# Multi-stage build for smaller final image
FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files first for layer caching
COPY package*.json ./
RUN npm ci --only=production

# Final stage
FROM node:20-alpine

# Run as non-root user (critical for security)
RUN addgroup -g 1001 -S mcpuser && \
    adduser -S mcpuser -u 1001

WORKDIR /app

# Copy only production dependencies
COPY --from=builder /app/node_modules ./node_modules
COPY --chown=mcpuser:mcpuser . .

USER mcpuser

# MCP servers communicate over stdio by default
CMD ["node", "dist/index.js"]

Dockerfile for the Official Filesystem MCP Server

The filesystem server needs a mounted volume to access your files. Here's a Dockerfile that exposes a configurable mount point:

FROM node:20-alpine

RUN addgroup -g 1001 -S mcpuser && \
    adduser -S mcpuser -u 1001

# Install the official server globally
RUN npm install -g @modelcontextprotocol/server-filesystem

# Create a workspace directory the container user can read
RUN mkdir -p /workspace && chown mcpuser:mcpuser /workspace

USER mcpuser

WORKDIR /workspace

ENTRYPOINT ["npx", "@modelcontextprotocol/server-filesystem"]
CMD ["/workspace"]

Run it with a volume mount:

docker run -v /your/project/path:/workspace \
  --read-only \
  --tmpfs /tmp \
  mcp-filesystem /workspace

Docker Compose for Multiple MCP Servers

In practice, you'll run multiple MCP servers simultaneously. Docker Compose is the right tool for this:

# docker-compose.yml
version: '3.9'

services:
  mcp-filesystem:
    image: mcp-filesystem:latest
    build:
      context: ./servers/filesystem
    volumes:
      - ./workspace:/workspace:ro
    environment:
      - NODE_ENV=production
    restart: unless-stopped
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL

  mcp-postgres:
    image: mcp-postgres:latest
    build:
      context: ./servers/postgres
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/mydb
    networks:
      - mcp-internal
      - db-network
    depends_on:
      - postgres
    restart: unless-stopped

  mcp-brave-search:
    image: mcp-brave-search:latest
    build:
      context: ./servers/brave-search
    environment:
      - BRAVE_API_KEY=${BRAVE_API_KEY}
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=mydb
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    networks:
      - db-network

networks:
  mcp-internal:
    driver: bridge
    internal: true
  db-network:
    driver: bridge

volumes:
  postgres_data:

Connecting Containerized MCP Servers to Claude Desktop

Claude Desktop and other MCP clients communicate with MCP servers over stdio. For containerized servers, you need to wrap the docker run command:

// claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/you/projects:/workspace:ro",
        "mcp-filesystem:latest",
        "/workspace"
      ]
    },
    "postgres": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network", "mcp-compose_mcp-internal",
        "-e", "DATABASE_URL=postgresql://user:pass@postgres:5432/mydb",
        "mcp-postgres:latest"
      ]
    }
  }
}

The -i flag keeps stdin open, which is required for stdio-based MCP communication. The --rm flag removes the container after each session.

Security Hardening for Production

MCP servers with sensitive access need hardened containers:

# docker-compose.yml (security-hardened service)
services:
  mcp-sensitive:
    image: mcp-sensitive:latest
    read_only: true
    tmpfs:
      - /tmp:size=50m
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    security_opt:
      - no-new-privileges:true
    mem_limit: 256m
    cpus: '0.5'
    user: "1001:1001"
    networks:
      - mcp-isolated

networks:
  mcp-isolated:
    driver: bridge
    internal: true

Environment Variable Management

Never bake API keys into Docker images. Use environment files with Docker Compose:

# .env (never commit this file)
BRAVE_API_KEY=BSA...
POSTGRES_PASSWORD=secure_password_here
GITHUB_TOKEN=ghp_...

# .env.example (commit this)
BRAVE_API_KEY=your_brave_api_key
POSTGRES_PASSWORD=your_db_password
GITHUB_TOKEN=your_github_token

For production deployments, use Docker secrets instead of environment variables for sensitive values:

# docker-compose.yml with secrets
services:
  mcp-postgres:
    secrets:
      - db_password
    environment:
      - DATABASE_PASSWORD_FILE=/run/secrets/db_password

secrets:
  db_password:
    external: true

Health Checks and Restart Policies

MCP servers can hang silently. Add health checks and appropriate restart policies:

services:
  mcp-filesystem:
    healthcheck:
      test: ["CMD", "node", "-e", "require('fs').accessSync('/workspace')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Multi-Architecture Builds for Team Environments

If your team mixes Apple Silicon and x86 machines, build multi-arch images:

# Build for both arm64 and amd64
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag yourregistry/mcp-filesystem:latest \
  --push \
  ./servers/filesystem

Debugging Containerized MCP Servers

When an MCP server behaves unexpectedly in a container:

# Run interactively to test stdio communication
docker run --rm -it \
  -v /your/project:/workspace:ro \
  mcp-filesystem:latest \
  /workspace

# Check logs for a running compose service
docker compose logs -f mcp-filesystem

# Inspect the running container
docker exec -it mcp-filesystem-container sh

Next Steps

Once you're comfortable with Docker deployments, consider moving to a managed container platform for zero-downtime restarts and auto-scaling. See our guides: Deploying MCP to AWS Lambda, Deploying MCP to Railway, and MCP Server Security Best Practices.

Browse the full MCP server directory to find servers ready for Docker deployment.