portainer-mcp/README.md

# Portainer MCP Server Suite

A comprehensive collection of Model Context Protocol (MCP) servers for managing Portainer Business Edition through natural language interfaces. This suite provides modular servers for different aspects of Portainer management, from user authentication to container orchestration.

## Quick Start

```bash
# Clone and setup
git clone https://github.com/yourusername/portainer-mcp.git
cd portainer-mcp

# Docker deployment (recommended)
cp .env.example .env
# Edit .env with your Portainer URL and API key
docker-compose pull
docker-compose up -d

# Or Python local installation
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python portainer_core_server.py
```

## Overview

The Portainer MCP Server Suite consists of specialized servers that work together to provide complete Portainer management capabilities:

- **[portainer-core](./portainer_core_server.py)** - Authentication, user management, teams, and RBAC ([Documentation](./README_CORE.md))
- **[portainer-environments](./portainer_environments_server.py)** - Environment and endpoint management ([Documentation](./README_ENVIRONMENTS.md))
- **[portainer-docker](./portainer_docker_server.py)** - Docker container and image operations ([Documentation](./README_DOCKER.md))
- **[portainer-kubernetes](./portainer_kubernetes_server.py)** - Kubernetes cluster management ([Documentation](./README_KUBERNETES.md))
- **[portainer-stacks](./portainer_stacks_server.py)** - Stack deployment and management ([Documentation](./README_STACKS.md))
- **[portainer-edge](./portainer_edge_server.py)** - Edge computing and device management ([Documentation](./README_EDGE.md))
- **[portainer-gitops](./portainer_gitops_server.py)** - GitOps automation and deployments ([Documentation](./README_GITOPS.md))

## Features

### Core Server (User & Access Management)
- User authentication and session management
- User CRUD operations with role assignments
- Teams creation and membership management
- Role-based access control (RBAC) configuration
- Resource access controls for fine-grained permissions
- System settings management

### Environments Server
- List and manage Docker/Kubernetes environments
- Create and configure endpoints
- Environment-specific settings
- Connection status monitoring

### Docker Server
- Container lifecycle management (26 tools)
- Image management and registry operations
- Volume and network management
- Docker Compose deployments
- Container logs and stats

### Kubernetes Server
- Cluster and namespace management (28 tools)
- Deployment and service operations
- ConfigMap and Secret management
- Pod operations and troubleshooting
- Ingress configuration

### Stacks Server
- Deploy stacks from templates or custom compose files
- Manage stack lifecycle
- Update stack configurations
- Environment variable management
- Stack migration between environments

### Edge Server
- Edge device registration and management
- Edge group operations
- Edge stack deployments
- Device monitoring and status
- Edge compute job scheduling

### GitOps Server
- Automated deployments from Git repositories
- Webhook and polling-based updates
- Multi-environment deployments
- Stack synchronization
- GitOps configuration management

## Requirements

- Python 3.8+
- Portainer Business Edition 2.19.0+
- Valid Portainer API key
- MCP-compatible client (e.g., Claude Desktop)

## Installation

### Option 1: Local Python Installation

1. Clone the repository:
```bash
git clone https://github.com/yourusername/portainer-mcp.git
cd portainer-mcp
```

2. Create a virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -r requirements.txt
# or manually: pip install mcp httpx aiohttp
```

### Option 2: Docker Installation (Recommended)

1. Clone the repository:
```bash
git clone https://github.com/yourusername/portainer-mcp.git
cd portainer-mcp
```

2. Configure environment and run:
```bash
cp .env.example .env
# Edit .env with your Portainer credentials
nano .env  # or use your preferred editor

# Pull pre-built images from registry
docker-compose pull
docker-compose up -d
```

See the [Docker Deployment Guide](./DOCKER.md) for detailed instructions.

## Configuration

### Environment Variables

Set these environment variables or create a `.env` file:

```bash
# Required
PORTAINER_URL=https://your-portainer-instance.com
PORTAINER_API_KEY=your-api-key-here

# Optional
PORTAINER_INSECURE=false  # Set to true for self-signed certificates
HTTP_TIMEOUT=30
MAX_RETRIES=3
```

### Generate API Key

1. Log in to your Portainer instance
2. Navigate to **My Account** → **Access Tokens**
3. Click **Add access token**
4. Copy the generated token

### Claude Desktop Configuration

#### Option 1: Local Python Installation

Add the servers to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "portainer-core": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/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"],
      "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)
```
"Create a new user named 'developer' with StandardUser role"
"List all teams and their members"
"Add user ID 5 to the DevOps team"
"Update security settings to allow volume browsing"
```

### Docker Operations (Docker Server)
```
"List all running containers in the production environment"
"Start the nginx container"
"Show logs for the app container from the last hour"
"Create a volume named 'data-volume' with local driver"
```

### Kubernetes Management (Kubernetes Server)
```
"List all deployments in the default namespace"
"Scale the web-app deployment to 3 replicas"
"Create a ConfigMap named 'app-config' with the provided data"
"Get pods in the production namespace"
```

### GitOps Automation (GitOps Server)
```
"Create a GitOps config for the nginx stack from my GitHub repo"
"Update all stacks from their Git repositories"
"Show GitOps configurations for environment ID 2"
"Force update the production stack from Git"
```

## Architecture

Each server follows a similar architecture:
- Async HTTP client for Portainer API communication
- MCP protocol implementation for tool exposure
- Error handling with descriptive messages
- Environment-based configuration
- Modular tool organization

## Security Considerations

- Always use HTTPS in production environments
- Rotate API tokens regularly
- Use environment-specific API keys with minimal required permissions
- Enable RBAC to restrict user access appropriately
- Monitor API usage and audit logs

## Troubleshooting

### Connection Issues
- Verify Portainer URL is accessible
- Check API key validity
- Ensure proper network connectivity
- For self-signed certificates, set `PORTAINER_INSECURE=true`

### Permission Errors
- Verify API key has required permissions
- Check RBAC settings for the user
- Ensure resource access controls allow the operation

### Server Errors
- Check Portainer logs for detailed error messages
- Verify Portainer version compatibility
- Enable debug logging with `DEBUG=true`

## Development

### Adding New Tools

1. Add tool definition in `handle_list_tools()`
2. Implement tool logic in `handle_call_tool()`
3. Test with various inputs and edge cases
4. Update documentation

### Testing

Currently, manual testing is recommended:
1. Start the server
2. Use an MCP client to invoke tools
3. Verify responses match expected behavior
4. Test error conditions

## Documentation

Each server has its own detailed documentation:

- **[Core Server Documentation](./README_CORE.md)** - User management, teams, RBAC, and settings
- **[Environments Server Documentation](./README_ENVIRONMENTS.md)** - Environment and endpoint management
- **[Docker Server Documentation](./README_DOCKER.md)** - Container, image, volume, and network operations
- **[Kubernetes Server Documentation](./README_KUBERNETES.md)** - Kubernetes cluster and resource management
- **[Stacks Server Documentation](./README_STACKS.md)** - Stack deployment and lifecycle management
- **[Edge Server Documentation](./README_EDGE.md)** - Edge device and edge compute management
- **[GitOps Server Documentation](./README_GITOPS.md)** - GitOps automation and continuous deployment
- **[Docker Deployment Guide](./DOCKER.md)** - Running MCP servers in Docker containers

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/new-tool`)
3. Commit your changes (`git commit -am 'Add new tool'`)
4. Push to the branch (`git push origin feature/new-tool`)
5. Create a Pull Request

## License

MIT License - see LICENSE file for details.

## Support

- For issues with the MCP servers, please open a GitHub issue
- For Portainer-specific questions, consult the [Portainer documentation](https://docs.portainer.io/)
- For MCP protocol questions, see the [MCP documentation](https://modelcontextprotocol.io/)