From ed37ee9e12837d2f6b33ce12501fa260c4c1ca62 Mon Sep 17 00:00:00 2001 From: Adolfo Delorenzo Date: Mon, 21 Jul 2025 16:25:34 -0300 Subject: [PATCH] docs: update Claude Desktop configuration for Docker containers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Docker-specific Claude Desktop configuration examples - Document both docker exec and docker run methods - Explain stdio communication requirements for MCP protocol - Include prerequisites and important notes for Docker usage - Update both README.md and DOCKER.md with consistent information The documentation now properly explains how to connect Claude Desktop to the MCP servers running in Docker containers, addressing the special requirements of stdio-based communication. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- DOCKER.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++---- README.md | 69 ++++++++++++++++++++++++++++++++++++++++++------------- 2 files changed, 117 insertions(+), 20 deletions(-) diff --git a/DOCKER.md b/DOCKER.md index edc1d9c..f4feac7 100644 --- a/DOCKER.md +++ b/DOCKER.md @@ -216,22 +216,82 @@ FROM python:3.11-slim ## Integration with Claude Desktop -When running in Docker, configure Claude Desktop to connect to the containerized servers: +Since MCP uses stdio for communication, connecting Claude Desktop to Docker containers requires special configuration. + +### Method 1: Docker Exec (Recommended) + +This method executes the Python script in an already-running container: ```json { "mcpServers": { "portainer-core": { - "url": "http://localhost:3000" + "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": { - "url": "http://localhost:3002" + "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"] } - // ... other servers } } ``` +**Prerequisites:** +1. Containers must be running: `docker-compose up -d` +2. Docker must be accessible from where Claude Desktop runs + +### Method 2: Docker Run (Alternative) + +This method creates a new container for each MCP session: + +```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 + } +} +``` + +**Pros:** Doesn't require pre-running containers +**Cons:** Slower startup, creates new container each time + +### Important Notes + +- 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 + ## Monitoring Monitor container health and resource usage: diff --git a/README.md b/README.md index 924cc7d..f6625e4 100644 --- a/README.md +++ b/README.md @@ -161,6 +161,8 @@ MAX_RETRIES=3 ### Claude Desktop Configuration +#### Option 1: Local Python Installation + Add the servers to your Claude Desktop configuration (`claude_desktop_config.json`): ```json @@ -181,27 +183,62 @@ Add the servers to your Claude Desktop configuration (`claude_desktop_config.jso "PORTAINER_URL": "https://your-portainer-instance.com", "PORTAINER_API_KEY": "your-api-key" } - }, - "portainer-kubernetes": { - "command": "/path/to/.venv/bin/python", - "args": ["/path/to/portainer_kubernetes_server.py"], - "env": { - "PORTAINER_URL": "https://your-portainer-instance.com", - "PORTAINER_API_KEY": "your-api-key" - } - }, - "portainer-gitops": { - "command": "/path/to/.venv/bin/python", - "args": ["/path/to/portainer_gitops_server.py"], - "env": { - "PORTAINER_URL": "https://your-portainer-instance.com", - "PORTAINER_API_KEY": "your-api-key" - } } + // Add other servers as needed... } } ``` +#### 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** +```json +{ + "mcpServers": { + "portainer-core": { + "command": "docker", + "args": ["exec", "-i", "portainer-mcp-core", "python", "portainer_core_server.py"], + "env": {} + }, + "portainer-docker": { + "command": "docker", + "args": ["exec", "-i", "portainer-mcp-docker", "python", "portainer_docker_server.py"], + "env": {} + } + // Add other servers as needed... + } +} +``` + +**Approach B: Docker Run Method (creates new container each time)** +```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": {} + } + // 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 + ## Usage Examples ### User Management (Core Server)