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

fix: correct MCP server documentation for Claude Desktop integration

Browse Source 
- 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
This commit is contained in:
Adolfo Delorenzo 2025-07-21 23:07:55 -03:00
parent ed37ee9e12
commit 98fb5905c3
2 changed files with 79 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
DOCKER.md
View File

@ -214,83 +214,58 @@ FROM python:3.11-slim
# Runtime stage... # 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 - ✅ **Docker is suitable for:** Running MCP servers as standalone HTTP/WebSocket services
{ - ❌ **Docker is NOT suitable for:** Direct Claude Desktop integration
"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"]
}
}
}
```
**Prerequisites:** ### For Claude Desktop Integration
1. Containers must be running: `docker-compose up -d`
2. Docker must be accessible from where Claude Desktop runs
### 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 The Docker deployment is useful for:
{
"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 1. **Development and Testing**
**Cons:** Slower startup, creates new container each time - 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 3. **CI/CD Pipelines**
- Ensure Docker daemon is running and accessible - Automated testing of MCP server functionality
- For Windows/Mac users, Docker Desktop must be running - Integration testing with Portainer instances
- Container names must match those in docker-compose.yml - 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 ## Monitoring

72
README.md
View File

@ -161,24 +161,30 @@ MAX_RETRIES=3
### Claude Desktop Configuration ### 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 ```json
{ {
"mcpServers": { "mcpServers": {
"portainer-core": { "portainer-core": {
"command": "/path/to/.venv/bin/python", "command": "python",
"args": ["/path/to/portainer_core_server.py"], "args": ["/absolute/path/to/portainer-mcp/portainer_core_server.py"],
"env": { "env": {
"PORTAINER_URL": "https://your-portainer-instance.com", "PORTAINER_URL": "https://your-portainer-instance.com",
"PORTAINER_API_KEY": "your-api-key" "PORTAINER_API_KEY": "your-api-key"
} }
}, },
"portainer-docker": { "portainer-docker": {
"command": "/path/to/.venv/bin/python", "command": "python",
"args": ["/path/to/portainer_docker_server.py"], "args": ["/absolute/path/to/portainer-mcp/portainer_docker_server.py"],
"env": { "env": {
"PORTAINER_URL": "https://your-portainer-instance.com", "PORTAINER_URL": "https://your-portainer-instance.com",
"PORTAINER_API_KEY": "your-api-key" "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) **Using virtual environment (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 ```json
{ {
"mcpServers": { "mcpServers": {
"portainer-core": { "portainer-core": {
"command": "docker", "command": "/absolute/path/to/portainer-mcp/.venv/bin/python",
"args": ["exec", "-i", "portainer-mcp-core", "python", "portainer_core_server.py"], "args": ["/absolute/path/to/portainer-mcp/portainer_core_server.py"],
"env": {} "env": {
"PORTAINER_URL": "https://your-portainer-instance.com",
"PORTAINER_API_KEY": "your-api-key"
}
}, },
"portainer-docker": { "portainer-docker": {
"command": "docker", "command": "/absolute/path/to/portainer-mcp/.venv/bin/python",
"args": ["exec", "-i", "portainer-mcp-docker", "python", "portainer_docker_server.py"], "args": ["/absolute/path/to/portainer-mcp/portainer_docker_server.py"],
"env": {} "env": {
"PORTAINER_URL": "https://your-portainer-instance.com",
"PORTAINER_API_KEY": "your-api-key"
}
} }
// Add other servers as needed... // Add other servers as needed...
} }
} }
``` ```
**Approach B: Docker Run Method (creates new container each time)** **Windows Configuration Example:**
```json ```json
{ {
"mcpServers": { "mcpServers": {
"portainer-core": { "portainer-core": {
"command": "docker", "command": "C:\\Python311\\python.exe",
"args": [ "args": ["C:\\Users\\YourName\\portainer-mcp\\portainer_core_server.py"],
"run", "--rm", "-i", "env": {
"--env-file", "/path/to/portainer-mcp/.env", "PORTAINER_URL": "https://your-portainer-instance.com",
"--network", "portainer-mcp_portainer-mcp", "PORTAINER_API_KEY": "your-api-key"
"git.oe74.net/adelorenzo/portainer-mcp/portainer-core:latest" }
],
"env": {}
} }
// Add other servers as needed...
} }
} }
``` ```
**Important Notes for Docker:** **Important Notes:**
- Ensure containers are running: `docker-compose up -d` - Always use absolute paths in the configuration
- The `-i` flag is crucial for interactive stdio communication - Ensure Python environment has required dependencies installed
- Approach A is faster but requires containers to be already running - The Docker deployment is for running the servers as standalone services, not for Claude Desktop integration
- Approach B is slower but doesn't require pre-running containers - 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 ## Usage Examples