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.

Overview

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

• portainer-core - Authentication, user management, teams, and RBAC (Documentation)
• portainer-environments - Environment and endpoint management (Documentation)
• portainer-docker - Docker container and image operations (Documentation)
• portainer-kubernetes - Kubernetes cluster management (Documentation)
• portainer-stacks - Stack deployment and management (Documentation)
• portainer-edge - Edge computing and device management (Documentation)
• portainer-gitops - GitOps automation and deployments (Documentation)

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

1. Clone the repository:

git clone https://github.com/yourusername/portainer-mcp.git
cd portainer-mcp

2. Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install mcp httpx aiohttp

Configuration

Environment Variables

Set these environment variables or create a .env file:

# 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

Add the servers to your Claude Desktop configuration (claude_desktop_config.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"
      }
    },
    "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"
      }
    }
  }
}

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 - User management, teams, RBAC, and settings
• Environments Server Documentation - Environment and endpoint management
• Docker Server Documentation - Container, image, volume, and network operations
• Kubernetes Server Documentation - Kubernetes cluster and resource management
• Stacks Server Documentation - Stack deployment and lifecycle management
• Edge Server Documentation - Edge device and edge compute management
• GitOps Server Documentation - GitOps automation and continuous deployment

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
• For MCP protocol questions, see the MCP documentation