portainer-mcp/DOCKER.md

Docker Deployment Guide for Portainer MCP Servers

This guide covers how to build and run the Portainer MCP servers using Docker containers.

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+
• Portainer Business Edition instance
• Valid Portainer API key

Quick Start

1. Clone the repository

   git clone https://github.com/yourusername/portainer-mcp.git
   cd portainer-mcp
   

2. Create environment file

   cp .env.example .env
   # Edit .env with your Portainer credentials
   nano .env  # or use your preferred editor
   

3. Pull images (or build locally)

   # Option A: Pull from registry (recommended)
   docker-compose pull
   
   # Option B: Build locally
   ./build-docker.sh all
   

4. Start all services

   docker-compose up -d
   

Individual Container Management

Building Containers

Build all containers:

./build-docker.sh all

Build specific container:

./build-docker.sh core
./build-docker.sh docker
./build-docker.sh kubernetes
# etc...

Running Containers

Run all services:

docker-compose up -d

Run specific service:

docker-compose up -d portainer-core
docker-compose up -d portainer-docker
# etc...

View logs:

docker-compose logs -f portainer-core
docker-compose logs -f portainer-docker
# etc...

Stop services:

docker-compose down

Container Details

Each MCP server runs in its own container with the following configuration:

Service	Container Name	Port	Purpose
portainer-core	portainer-mcp-core	3000	User management, teams, RBAC
portainer-environments	portainer-mcp-environments	3001	Environment management
portainer-docker	portainer-mcp-docker	3002	Docker operations
portainer-kubernetes	portainer-mcp-kubernetes	3003	Kubernetes management
portainer-stacks	portainer-mcp-stacks	3004	Stack deployment
portainer-edge	portainer-mcp-edge	3005	Edge computing
portainer-gitops	portainer-mcp-gitops	3006	GitOps automation

Environment Variables

All containers use a shared .env file for configuration. The docker-compose.yml file is configured to automatically load environment variables from this file using the env_file directive.

# docker-compose.yml snippet
services:
  portainer-core:
    image: git.oe74.net/adelorenzo/portainer-mcp/portainer-core:latest
    env_file:
      - .env

See .env.example for a complete list of available environment variables with detailed documentation and troubleshooting tips.

Key Variables:

• PORTAINER_URL - Your Portainer instance URL (required)
• PORTAINER_API_KEY - Your Portainer API token (required)
• PORTAINER_INSECURE - Set to true for self-signed certificates
• HTTP_TIMEOUT - Request timeout in seconds
• MAX_RETRIES - Number of retry attempts

Docker Compose Configuration

The docker-compose.yml file defines all services with:

• Individual port mappings
• Shared environment variables
• Automatic restart policies
• Isolated network for inter-container communication

Production Deployment

For production environments, consider:

1. Use Docker Swarm or Kubernetes

   # Deploy as stack in Swarm
   docker stack deploy -c docker-compose.yml portainer-mcp
   

2. Enable health checks Add to each service in docker-compose.yml:

   healthcheck:
     test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
     interval: 30s
     timeout: 10s
     retries: 3
   

3. Use secrets for API keys

   secrets:
     portainer_api_key:
       external: true
   

4. Configure resource limits

   deploy:
     resources:
       limits:
         cpus: '0.5'
         memory: 256M
   

Troubleshooting

Container won't start

• Check logs: docker-compose logs portainer-<service>
• Verify environment variables in .env
• Ensure Portainer URL is accessible from container

Connection errors

• For self-signed certificates, set PORTAINER_INSECURE=true
• Check network connectivity: docker exec portainer-mcp-core curl https://your-portainer-url

Permission errors

• Verify API key has required permissions
• Check Portainer RBAC settings

Security Considerations

1. Never commit .env file - It contains sensitive credentials
2. Use read-only mounts where possible
3. Run containers as non-root user (already configured)
4. Enable TLS for MCP connections in production
5. Regularly update base images and dependencies

Advanced Configuration

Custom Network

networks:
  portainer-mcp:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

Volume Mounts

For persistent logs or configuration:

volumes:
  - ./logs:/app/logs
  - ./config:/app/config:ro

Multi-stage Builds

The Dockerfiles use single-stage builds for simplicity. For smaller images:

FROM python:3.11-slim AS builder
# Build stage...

FROM python:3.11-slim
# Runtime stage...

Docker Deployment vs Claude Desktop Integration

Important: The Docker deployment described in this guide is for running MCP servers as standalone services, NOT for integrating with Claude Desktop.

Why Docker Cannot Be Used with Claude Desktop

MCP (Model Context Protocol) servers communicate via stdio (standard input/output), which requires direct process execution. Docker containers add layers of abstraction that interfere with this communication model. Therefore:

• ✅ Docker is suitable for: Running MCP servers as standalone HTTP/WebSocket services
• ❌ Docker is NOT suitable for: Direct Claude Desktop integration

For Claude Desktop Integration

To use these MCP servers with Claude Desktop, you must run them locally as Python processes. See the main README.md for proper configuration instructions.

Docker Use Cases

The Docker deployment is useful for:

1. Development and Testing

   • Isolated environment for testing MCP servers
   • Easy dependency management
   • Consistent development environment across teams

2. Standalone Service Deployment

   • Running MCP servers as HTTP/REST APIs
   • Integrating with other automation tools
   • Building custom frontends or APIs on top of MCP servers

3. CI/CD Pipelines

   • Automated testing of MCP server functionality
   • Integration testing with Portainer instances
   • Deployment to container orchestration platforms

Alternative Integration Patterns

If you need to use Docker-deployed MCP servers with Claude or other MCP clients:

1. Build an HTTP Bridge

   • Create an HTTP API wrapper around MCP servers
   • Use the Docker containers as backend services
   • Connect Claude to the HTTP bridge (requires custom integration)

2. Use Remote Execution

   • Deploy MCP servers on remote hosts
   • Use SSH or other remote execution methods
   • Not officially supported by Claude Desktop

3. Hybrid Approach

   • Use Docker for development/testing
   • Run locally for Claude Desktop integration
   • Share configuration via environment files

Monitoring

Monitor container health and resource usage:

# View resource usage
docker stats

# Check container health
docker ps --format "table {{.Names}}\t{{.Status}}"

# Export metrics
docker-compose ps --format json