adelorenzo/portainer-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update Claude Desktop configuration for Docker containers

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Adolfo Delorenzo 2025-07-21 16:25:34 -03:00
parent 10dfd606c0
commit ed37ee9e12
2 changed files with 117 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
DOCKER.md
View File

@ -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:

69
README.md
View File

@ -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)