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

344
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 ## Features
- **Authentication**: JWT token-based authentication with Portainer API ### Core Server (User & Access Management)
- **User Management**: Complete CRUD operations for users - User authentication and session management
- **Settings Management**: Portainer instance configuration - User CRUD operations with role assignments
- **Health Monitoring**: Server and service health checks - Teams creation and membership management
- **Fault Tolerance**: Circuit breaker pattern with automatic recovery - Role-based access control (RBAC) configuration
- **Structured Logging**: JSON-formatted logs with correlation IDs - 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 ## Requirements
- Python 3.8+ - Python 3.8+
- Portainer Business Edition instance - Portainer Business Edition 2.19.0+
- Valid Portainer API key - Valid Portainer API key
- MCP-compatible client (e.g., Claude Desktop)
## Installation ## Installation
### Using pip 1. Clone the repository:
```bash ```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 ```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 ```bash
# No installation needed - runs directly pip install mcp httpx aiohttp
uvx --from . portainer-core-mcp
```
### Using npm/npx
```bash
npm install -g portainer-core-mcp
``` ```
## Configuration ## Configuration
### Environment Variables ### Environment Variables
Create a `.env` file or set environment variables: Set these environment variables or create a `.env` file:
```bash ```bash
# Required # Required
@ -56,162 +103,161 @@ PORTAINER_URL=https://your-portainer-instance.com
PORTAINER_API_KEY=your-api-key-here PORTAINER_API_KEY=your-api-key-here
# Optional # Optional
PORTAINER_INSECURE=false # Set to true for self-signed certificates
HTTP_TIMEOUT=30 HTTP_TIMEOUT=30
MAX_RETRIES=3 MAX_RETRIES=3
LOG_LEVEL=INFO
DEBUG=false
``` ```
### Generate API Key ### Generate API Key
1. Log in to your Portainer instance 1. Log in to your Portainer instance
2. Go to **User Settings** > **API Tokens** 2. Navigate to **My Account** → **Access Tokens**
3. Click **Add API Token** 3. Click **Add access token**
4. Copy the generated 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 ```json
{
```bash "mcpServers": {
python run_server.py "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 ### User Management (Core Server)
uv run python run_server.py ```
"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 ### Docker Operations (Docker Server)
```
```bash "List all running containers in the production environment"
uvx --from . portainer-core-mcp "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 ### Kubernetes Management (Kubernetes Server)
```
```bash "List all deployments in the default namespace"
npx portainer-core-mcp "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 ### GitOps Automation (GitOps Server)
```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
``` ```
"Create a GitOps config for the nginx stack from my GitHub repo"
## Available Tools "Update all stacks from their Git repositories"
"Show GitOps configurations for environment ID 2"
The MCP server provides the following tools: "Force update the production stack from Git"
### 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
``` ```
## Architecture ## 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 ## Security Considerations
- **Service Layer**: Abstracts Portainer API interactions
- **Models Layer**: Defines data structures and validation
- **Utils Layer**: Provides utility functions and helpers
## 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 ## Troubleshooting
- JWT tokens are handled securely and never logged
- Input validation on all parameters ### Connection Issues
- Rate limiting to prevent abuse - Verify Portainer URL is accessible
- Circuit breaker pattern for fault tolerance - 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 ## Contributing
1. Fork the repository 1. Fork the repository
2. Create a feature branch 2. Create a feature branch (`git checkout -b feature/new-tool`)
3. Make your changes 3. Commit your changes (`git commit -am 'Add new tool'`)
4. Add tests for new functionality 4. Push to the branch (`git push origin feature/new-tool`)
5. Ensure all tests pass 5. Create a Pull Request
6. Submit a pull request
## License ## 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/)