Docker Deployment

This guide explains how to use Docker with the MCP Inspector project, leveraging the existing mcpjam/mcp-inspector image on Docker Hub.

Quick Start

Using Pre-built Image from Docker Hub

This is the simplest way to run the Inspector in a containerized environment.

# Pull and run the latest version
docker run -p 3001:3001 mcpjam/mcp-inspector:latest

The application will be available at http://localhost:3001.

Building Locally

If you have the source code, you can build and run the Docker image locally.

# Build the production image
npm run docker:build

# Run the locally built image
npm run docker:run

Dockerfile Explained

The Dockerfile uses a multi-stage build to create a small and efficient production image.

# Stage 1: Dependencies base (shared)
FROM node:20-alpine AS deps-base
WORKDIR /app
COPY package.json package-lock.json ./
COPY client/package*.json ./client/
COPY server/package*.json ./server/
RUN npm install --include=dev
RUN cd client && npm install --include=dev  
RUN cd server && npm install --include=dev

# Stage 2: Build client
FROM deps-base AS client-builder
COPY shared/ ./shared/
COPY client/ ./client/
RUN cd client && npm run build

# Stage 3: Build server  
FROM deps-base AS server-builder
COPY shared/ ./shared/
COPY server/ ./server/
COPY client/ ./client/
RUN cd server && npm run build

# Stage 4: Production image
FROM node:20-alpine AS production
RUN apk add --no-cache dumb-init
WORKDIR /app

# Copy built applications
COPY --from=client-builder /app/dist/client ./dist/client
COPY --from=server-builder /app/dist/server ./dist/server

# Copy server package.json and install production dependencies
COPY --from=server-builder /app/server/package.json ./package.json
RUN npm install --production

# ... (user creation, port exposure, entrypoint)

CMD ["sh", "-c", "NODE_ENV=production node dist/server/index.cjs"]
  • Stage 1 (deps-base): Installs all dependencies (including dev dependencies) to leverage Docker's layer caching.
  • Stage 2 & 3 (client-builder, server-builder): Build the React frontend and Hono backend respectively.
  • Stage 4 (production): Copies only the built artifacts and production dependencies into a clean Alpine image. This results in a much smaller final image.
  • Security: Runs the application as a non-root user (mcpjam) and uses dumb-init for proper signal handling.

Health Checks

The Docker container includes a health check to ensure the application is running correctly. It periodically checks the /health endpoint.

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD node -e "require('http').request('http://localhost:3001/health', (res) => process.exit(res.statusCode === 200 ? 0 : 1)).end()"

CI/CD Integration

The project includes a GitHub Actions workflow (.github/workflows/docker-build-deploy.yml) that automatically builds and pushes a new Docker image to Docker Hub whenever a new version tag (e.g., v1.2.3) is pushed to the repository.