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

docs: update main README to reflect complete MCP server suite

Browse Source 
- Replace outdated single-server documentation with comprehensive suite overview
- Document all 7 specialized MCP servers with their capabilities
- Add proper installation and configuration instructions for the suite
- Include usage examples for each server type
- Update Claude Desktop configuration examples
- Add security considerations and troubleshooting guide

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Adolfo Delorenzo 2025-07-19 00:51:13 -03:00
parent d5f8ae5794
commit 320777fd3a
1 changed files with 196 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

346
README.md
View File

@ -1,54 +1,101 @@
# Portainer Core MCP Server
# Portainer MCP Server Suite
A Model Context Protocol (MCP) server that provides authentication and user management functionality for Portainer Business Edition.
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](./portainer_core_server.py)** - Authentication, user management, teams, and RBAC
- **[portainer-environments](./portainer_environments_server.py)** - Environment and endpoint management
- **[portainer-docker](./portainer_docker_server.py)** - Docker container and image operations
- **[portainer-kubernetes](./portainer_kubernetes_server.py)** - Kubernetes cluster management
- **[portainer-stacks](./portainer_stacks_server.py)** - Stack deployment and management
- **[portainer-edge](./portainer_edge_server.py)** - Edge computing and device management
- **[portainer-gitops](./portainer_gitops_server.py)** - GitOps automation and deployments
## Features
- **Authentication**: JWT token-based authentication with Portainer API
- **User Management**: Complete CRUD operations for users
- **Settings Management**: Portainer instance configuration
- **Health Monitoring**: Server and service health checks
- **Fault Tolerance**: Circuit breaker pattern with automatic recovery
- **Structured Logging**: JSON-formatted logs with correlation IDs
### 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 instance
- Portainer Business Edition 2.19.0+
- Valid Portainer API key
- MCP-compatible client (e.g., Claude Desktop)
## Installation
### Using pip
1. Clone the repository:
```bash
pip install -e .
git clone https://github.com/yourusername/portainer-mcp.git
cd portainer-mcp
```
### Using uv (recommended)
2. Create a virtual environment:
```bash
uv pip install -e .
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
### Using uvx (run without installing)
3. Install dependencies:
```bash
# No installation needed - runs directly
uvx --from . portainer-core-mcp
```
### Using npm/npx
```bash
npm install -g portainer-core-mcp
pip install mcp httpx aiohttp
```
## Configuration
### Environment Variables
Create a `.env` file or set environment variables:
Set these environment variables or create a `.env` file:
```bash
# Required
@ -56,162 +103,161 @@ 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
LOG_LEVEL=INFO
DEBUG=false
```
### Generate API Key
1. Log in to your Portainer instance
2. Go to **User Settings** > **API Tokens**
3. Click **Add API Token**
2. Navigate to **My Account** → **Access Tokens**
3. Click **Add access token**
4. Copy the generated token
## Usage
### Claude Desktop Configuration
### Start the Server
Add the servers to your Claude Desktop configuration (`claude_desktop_config.json`):
#### Using Python
```bash
python run_server.py
```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"
}
}
}
}
```
#### Using uv
## Usage Examples
```bash
uv run python run_server.py
### 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"
```
#### Using uvx
```bash
uvx --from . portainer-core-mcp
### 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"
```
#### Using npm/npx
```bash
npx portainer-core-mcp
### 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"
```
### Environment Setup
```bash
# Copy example environment file
cp .env.example .env
# Edit configuration
nano .env
# Start server (choose your preferred method)
python run_server.py
# OR
uvx --from . portainer-core-mcp
### GitOps Automation (GitOps Server)
```
## Available Tools
The MCP server provides the following tools:
### Authentication
- `authenticate` - Login with username/password
- `generate_token` - Generate API tokens
- `get_current_user` - Get current user info
### User Management
- `list_users` - List all users
- `create_user` - Create new user
- `update_user` - Update user details
- `delete_user` - Delete user
### Settings
- `get_settings` - Get Portainer settings
- `update_settings` - Update configuration
### Health
- `health_check` - Server health status
## Available Resources
- `portainer://users` - User management data
- `portainer://settings` - Configuration settings
- `portainer://health` - Server health status
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/yourusername/portainer-core-mcp.git
cd portainer-core-mcp
# Install development dependencies
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
```
### Testing
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=src/portainer_core --cov-report=html
# Run only unit tests
pytest -m unit
# Run only integration tests
pytest -m integration
```
### Code Quality
```bash
# Format code
black src tests
isort src tests
# Lint code
flake8 src tests
# Type checking
mypy src
"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
The server follows a layered 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
- **MCP Server Layer**: Handles MCP protocol communication
- **Service Layer**: Abstracts Portainer API interactions
- **Models Layer**: Defines data structures and validation
- **Utils Layer**: Provides utility functions and helpers
## Security Considerations
## Security
- 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
- All API communications use HTTPS
- JWT tokens are handled securely and never logged
- Input validation on all parameters
- Rate limiting to prevent abuse
- Circuit breaker pattern for fault tolerance
## 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
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
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.
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/)