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
This commit is contained in:
parent
ed37ee9e12
commit
98fb5905c3
107
DOCKER.md
107
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
|
||||
|
||||
|
||||
72
README.md
72
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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user