Portainer Core MCP Server

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

Features

Authentication & Session Management: JWT token handling and user authentication
User Management: Create, read, update, and delete users
Settings Management: Retrieve and update Portainer settings
Secure Token Handling: Automatic token refresh and secure storage
Error Handling: Comprehensive error handling with retry logic
Circuit Breaker: Fault tolerance for external API calls

Installation

pip install portainer-core-mcp

Configuration

Set the following environment variables:

PORTAINER_URL=https://your-portainer-instance.com
PORTAINER_API_KEY=your-api-token  # Optional, for API key authentication
PORTAINER_USERNAME=admin          # For username/password authentication
PORTAINER_PASSWORD=your-password  # For username/password authentication

Usage

As MCP Server

portainer-core-mcp

Programmatic Usage

from portainer_core.server import PortainerCoreMCPServer

server = PortainerCoreMCPServer()
# Use server instance

Available MCP Tools

authenticate - Login with username/password
generate_token - Generate API token
get_current_user - Get authenticated user info
list_users - List all users
create_user - Create new user
update_user - Update user details
delete_user - Delete user
get_settings - Get Portainer settings
update_settings - Update settings

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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

MIT License - see LICENSE file for details.

2.8 KiB Raw Blame History