portainer-mcp/README.md

Portainer Core MCP Server

A Model Context Protocol (MCP) server that provides authentication and user management functionality for Portainer Business Edition.

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

Requirements

• Python 3.8+
• Portainer Business Edition instance
• Valid Portainer API key

Installation

Using pip

pip install -e .

Using uv (recommended)

uv pip install -e .

Using uvx (run without installing)

# No installation needed - runs directly
uvx --from . portainer-core-mcp

Using npm/npx

npm install -g portainer-core-mcp

Configuration

Environment Variables

Create a .env file or set environment variables:

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

# Optional
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
4. Copy the generated token

Usage

Start the Server

Using Python

python run_server.py

Using uv

uv run python run_server.py

Using uvx

uvx --from . portainer-core-mcp

Using npm/npx

npx portainer-core-mcp

Environment Setup

# 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

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

# 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

# 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

# Format code
black src tests
isort src tests

# Lint code
flake8 src tests

# Type checking
mypy src

Architecture

The server follows a layered architecture:

• 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

• 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

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

License

MIT License - see LICENSE file for details.