Docker Deployment Guide for pyResToolbox MCP Server

This guide explains how to deploy the pyResToolbox MCP server using Docker and Docker Compose.

Prerequisites

Docker (version 20.10 or higher)
Docker Compose (version 2.0 or higher)

Quick Start

Option 1: HTTP Server (Recommended for Web Access)

# Start HTTP server on port 8000
docker-compose --profile http up -d

# Check logs
docker-compose logs -f pyrestoolbox-mcp-http

# Stop server
docker-compose --profile http down

Access the server at: http://localhost:8000

Option 2: SSE Server (Server-Sent Events)

# Start SSE server on port 8001
docker-compose --profile sse up -d

# Check logs
docker-compose logs -f pyrestoolbox-mcp-sse

# Stop server
docker-compose --profile sse down

Access the server at: http://localhost:8001

Option 3: STDIO Server (for Programmatic Access)

# Start STDIO server
docker-compose --profile stdio up -d

# Interact with server
docker exec -it pyrestoolbox-mcp-stdio fastmcp run server.py

# Stop server
docker-compose --profile stdio down

Building the Docker Image

Build with Docker

# Build the image
docker build -t pyrestoolbox-mcp:latest .

# Run with STDIO
docker run -it pyrestoolbox-mcp:latest

# Run with HTTP
docker run -p 8000:8000 pyrestoolbox-mcp:latest \
  fastmcp run server.py --transport http --host 0.0.0.0 --port 8000

Build with Docker Compose

# Build all services
docker-compose build

# Build specific profile
docker-compose --profile http build

Environment Configuration

Copy .env.docker to .env and customize:

cp .env.docker .env

Available environment variables:

# HTTP Server Port
MCP_HTTP_PORT=8000

# SSE Server Port
MCP_SSE_PORT=8001

# Logging Level
LOG_LEVEL=INFO

Docker Compose Profiles

The docker-compose.yml uses profiles to run different transport modes:

Profile	Service Name	Port	Use Case
`http`	pyrestoolbox-mcp-http	8000	Web/HTTP access
`sse`	pyrestoolbox-mcp-sse	8001	Server-Sent Events
`stdio`	pyrestoolbox-mcp-stdio	N/A	Programmatic/CLI access

Common Operations

Start Server

# HTTP server
docker-compose --profile http up -d

# Multiple profiles
docker-compose --profile http --profile sse up -d

View Logs

# Follow logs
docker-compose logs -f

# Specific service
docker-compose logs -f pyrestoolbox-mcp-http

# Last 100 lines
docker-compose logs --tail=100 pyrestoolbox-mcp-http

Stop Server

# Stop specific profile
docker-compose --profile http down

# Stop all
docker-compose down

# Stop and remove volumes
docker-compose down -v

Restart Server

# Restart specific service
docker-compose restart pyrestoolbox-mcp-http

# Restart all
docker-compose restart

Execute Commands

# Run test inside container
docker exec pyrestoolbox-mcp-http python test_server.py

# Access shell
docker exec -it pyrestoolbox-mcp-http /bin/bash

# Check server status
docker exec pyrestoolbox-mcp-http python -c "from pyrestoolbox_mcp import mcp; print(mcp.name)"

Health Checks

The HTTP and SSE services include health checks:

# Check container health
docker inspect --format='{{.State.Health.Status}}' pyrestoolbox-mcp-http

# View health check logs
docker inspect --format='{{json .State.Health}}' pyrestoolbox-mcp-http | jq

Integration Examples

With Claude Desktop (HTTP Transport)

Start HTTP server:

docker-compose --profile http up -d

Update Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "pyrestoolbox": {
      "url": "http://localhost:8000"
    }
  }
}

With Python Client (HTTP)

import httpx

# Call a tool via HTTP
response = httpx.post(
    "http://localhost:8000/tools/oil_bubble_point",
    json={
        "api": 35.0,
        "degf": 180.0,
        "rsb": 800.0,
        "sg_g": 0.75,
        "method": "VALMC"
    }
)
print(response.json())

With Docker Network

To connect from another container:

services:
  your-app:
    image: your-app:latest
    networks:
      - pyrestoolbox-mcp-network
    environment:
      - MCP_SERVER_URL=http://pyrestoolbox-mcp-http:8000

networks:
  pyrestoolbox-mcp-network:
    external: true

Production Deployment

Security Considerations

Use a reverse proxy (nginx, traefik) for HTTPS:

services:
  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - pyrestoolbox-mcp-http

Add authentication using FastMCP auth providers
Limit resource usage:

services:
  pyrestoolbox-mcp-http:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

Scaling

Run multiple replicas:

services:
  pyrestoolbox-mcp-http:
    deploy:
      replicas: 3
    # ... rest of config

Or use Docker Swarm/Kubernetes for orchestration.

Troubleshooting

Container Won't Start

# Check logs
docker-compose logs pyrestoolbox-mcp-http

# Check if port is in use
lsof -i :8000

# Remove and rebuild
docker-compose down
docker-compose build --no-cache
docker-compose --profile http up

Import Errors

# Verify installation
docker exec pyrestoolbox-mcp-http pip list | grep pyrestoolbox

# Reinstall
docker-compose build --no-cache

Permission Issues

The container runs as non-root user (uid 1000). If you have permission issues:

# Check user
docker exec pyrestoolbox-mcp-http whoami

# Fix ownership
docker exec -u root pyrestoolbox-mcp-http chown -R mcp:mcp /app

Network Issues

# Check network
docker network ls | grep mcp

# Inspect network
docker network inspect pyrestoolbox-mcp-network

# Recreate network
docker network rm pyrestoolbox-mcp-network
docker-compose up -d

Maintenance

Update Image

# Pull latest code
git pull

# Rebuild image
docker-compose build

# Restart with new image
docker-compose --profile http down
docker-compose --profile http up -d

Cleanup

# Remove unused images
docker image prune -a

# Remove all related containers and images
docker-compose down --rmi all

# Remove volumes
docker volume rm pyrestoolbox-mcp-data

Advanced Configuration

Custom Dockerfile

Create Dockerfile.custom:

FROM pyrestoolbox-mcp:latest

# Add custom dependencies
RUN pip install your-custom-package

# Add custom configuration
COPY custom-config.py /app/

Build:

docker build -f Dockerfile.custom -t pyrestoolbox-mcp:custom .

Development Mode

Mount source code for live development:

services:
  pyrestoolbox-mcp-dev:
    build: .
    volumes:
      - ./src:/app/src:ro
    command: ["fastmcp", "run", "server.py", "--reload"]

Monitoring

Container Stats

# Real-time stats
docker stats pyrestoolbox-mcp-http

# Resource usage
docker-compose top

Logs to File

# Export logs
docker-compose logs > mcp-server.log

# With timestamp
docker-compose logs --timestamps > mcp-server.log

Support

For Docker-specific issues:

Check logs: docker-compose logs
Verify health: docker-compose ps
Test connectivity: curl http://localhost:8000

For application issues, see README.md and QUICKSTART.md.

FilesExpand file tree

DOCKER.md

Latest commit

History