From 98fb5905c3f63ddb2eb2ec5b26404a2ac35a888a Mon Sep 17 00:00:00 2001 From: Adolfo Delorenzo Date: Mon, 21 Jul 2025 23:07:55 -0300 Subject: [PATCH] fix: correct MCP server documentation for Claude Desktop integration - Remove incorrect Docker-based configuration methods from README.md - Clarify in DOCKER.md that Docker cannot be used for Claude Desktop integration - Add proper local Python execution examples for Claude Desktop - Explain MCP stdio protocol limitations with Docker containers - Add Windows-specific configuration example --- DOCKER.md | 107 +++++++++++++++++++++--------------------------------- README.md | 72 +++++++++++++++++++----------------- 2 files changed, 79 insertions(+), 100 deletions(-) diff --git a/DOCKER.md b/DOCKER.md index f4feac7..6c0337a 100644 --- a/DOCKER.md +++ b/DOCKER.md @@ -214,83 +214,58 @@ FROM python:3.11-slim # Runtime stage... ``` -## Integration with Claude Desktop +## Docker Deployment vs Claude Desktop Integration -Since MCP uses stdio for communication, connecting Claude Desktop to Docker containers requires special configuration. +**Important:** The Docker deployment described in this guide is for running MCP servers as standalone services, NOT for integrating with Claude Desktop. -### Method 1: Docker Exec (Recommended) +### Why Docker Cannot Be Used with Claude Desktop -This method executes the Python script in an already-running container: +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: -```json -{ - "mcpServers": { - "portainer-core": { - "command": "docker", - "args": ["exec", "-i", "portainer-mcp-core", "python", "portainer_core_server.py"] - }, - "portainer-environments": { - "command": "docker", - "args": ["exec", "-i", "portainer-mcp-environments", "python", "portainer_environments_server.py"] - }, - "portainer-docker": { - "command": "docker", - "args": ["exec", "-i", "portainer-mcp-docker", "python", "portainer_docker_server.py"] - }, - "portainer-kubernetes": { - "command": "docker", - "args": ["exec", "-i", "portainer-mcp-kubernetes", "python", "portainer_kubernetes_server.py"] - }, - "portainer-stacks": { - "command": "docker", - "args": ["exec", "-i", "portainer-mcp-stacks", "python", "portainer_stacks_server.py"] - }, - "portainer-edge": { - "command": "docker", - "args": ["exec", "-i", "portainer-mcp-edge", "python", "portainer_edge_server.py"] - }, - "portainer-gitops": { - "command": "docker", - "args": ["exec", "-i", "portainer-mcp-gitops", "python", "portainer_gitops_server.py"] - } - } -} -``` +- ✅ **Docker is suitable for:** Running MCP servers as standalone HTTP/WebSocket services +- ❌ **Docker is NOT suitable for:** Direct Claude Desktop integration -**Prerequisites:** -1. Containers must be running: `docker-compose up -d` -2. Docker must be accessible from where Claude Desktop runs +### For Claude Desktop Integration -### Method 2: Docker Run (Alternative) +To use these MCP servers with Claude Desktop, you must run them locally as Python processes. See the main [README.md](./README.md#claude-desktop-configuration) for proper configuration instructions. -This method creates a new container for each MCP session: +### Docker Use Cases -```json -{ - "mcpServers": { - "portainer-core": { - "command": "docker", - "args": [ - "run", "--rm", "-i", - "--env-file", "/path/to/portainer-mcp/.env", - "--network", "portainer-mcp_portainer-mcp", - "git.oe74.net/adelorenzo/portainer-mcp/portainer-core:latest" - ] - } - // ... similar for other servers - } -} -``` +The Docker deployment is useful for: -**Pros:** Doesn't require pre-running containers -**Cons:** Slower startup, creates new container each time +1. **Development and Testing** + - Isolated environment for testing MCP servers + - Easy dependency management + - Consistent development environment across teams -### Important Notes +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 -- The `-i` flag is **required** for stdio communication -- Ensure Docker daemon is running and accessible -- For Windows/Mac users, Docker Desktop must be running -- Container names must match those in docker-compose.yml +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 diff --git a/README.md b/README.md index f6625e4..19a6dd2 100644 --- a/README.md +++ b/README.md @@ -161,24 +161,30 @@ MAX_RETRIES=3 ### Claude Desktop Configuration -#### Option 1: Local Python Installation +**Important:** MCP servers communicate via stdio protocol and must be run as local processes. Docker containers cannot be directly used with Claude Desktop due to this protocol limitation. -Add the servers to your Claude Desktop configuration (`claude_desktop_config.json`): +Add the servers to your Claude Desktop configuration. The location varies by platform: +- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` +- Windows: `%APPDATA%\Claude\claude_desktop_config.json` + +#### Configuration Examples + +**Using Python directly:** ```json { "mcpServers": { "portainer-core": { - "command": "/path/to/.venv/bin/python", - "args": ["/path/to/portainer_core_server.py"], + "command": "python", + "args": ["/absolute/path/to/portainer-mcp/portainer_core_server.py"], "env": { "PORTAINER_URL": "https://your-portainer-instance.com", "PORTAINER_API_KEY": "your-api-key" } }, "portainer-docker": { - "command": "/path/to/.venv/bin/python", - "args": ["/path/to/portainer_docker_server.py"], + "command": "python", + "args": ["/absolute/path/to/portainer-mcp/portainer_docker_server.py"], "env": { "PORTAINER_URL": "https://your-portainer-instance.com", "PORTAINER_API_KEY": "your-api-key" @@ -189,55 +195,53 @@ Add the servers to your Claude Desktop configuration (`claude_desktop_config.jso } ``` -#### Option 2: Docker Containers (Recommended) - -**Note:** MCP protocol uses stdio for communication, which requires special handling for Docker containers. - -For Docker deployment, you have two approaches: - -**Approach A: Docker Exec Method** +**Using virtual environment (recommended):** ```json { "mcpServers": { "portainer-core": { - "command": "docker", - "args": ["exec", "-i", "portainer-mcp-core", "python", "portainer_core_server.py"], - "env": {} + "command": "/absolute/path/to/portainer-mcp/.venv/bin/python", + "args": ["/absolute/path/to/portainer-mcp/portainer_core_server.py"], + "env": { + "PORTAINER_URL": "https://your-portainer-instance.com", + "PORTAINER_API_KEY": "your-api-key" + } }, "portainer-docker": { - "command": "docker", - "args": ["exec", "-i", "portainer-mcp-docker", "python", "portainer_docker_server.py"], - "env": {} + "command": "/absolute/path/to/portainer-mcp/.venv/bin/python", + "args": ["/absolute/path/to/portainer-mcp/portainer_docker_server.py"], + "env": { + "PORTAINER_URL": "https://your-portainer-instance.com", + "PORTAINER_API_KEY": "your-api-key" + } } // Add other servers as needed... } } ``` -**Approach B: Docker Run Method (creates new container each time)** +**Windows Configuration Example:** ```json { "mcpServers": { "portainer-core": { - "command": "docker", - "args": [ - "run", "--rm", "-i", - "--env-file", "/path/to/portainer-mcp/.env", - "--network", "portainer-mcp_portainer-mcp", - "git.oe74.net/adelorenzo/portainer-mcp/portainer-core:latest" - ], - "env": {} + "command": "C:\\Python311\\python.exe", + "args": ["C:\\Users\\YourName\\portainer-mcp\\portainer_core_server.py"], + "env": { + "PORTAINER_URL": "https://your-portainer-instance.com", + "PORTAINER_API_KEY": "your-api-key" + } } - // Add other servers as needed... } } ``` -**Important Notes for Docker:** -- Ensure containers are running: `docker-compose up -d` -- The `-i` flag is crucial for interactive stdio communication -- Approach A is faster but requires containers to be already running -- Approach B is slower but doesn't require pre-running containers +**Important Notes:** +- Always use absolute paths in the configuration +- Ensure Python environment has required dependencies installed +- The Docker deployment is for running the servers as standalone services, not for Claude Desktop integration +- After editing the configuration, restart Claude Desktop for changes to take effect +- For Windows users, use forward slashes in paths or escape backslashes ## Usage Examples