portainer-mcp/USAGE.md

Portainer Core MCP Server Usage Guide

Quick Start

1. Set Required Environment Variables

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

2. Generate Portainer API Key

1. Log in to your Portainer instance
2. Navigate to User Settings > API Tokens
3. Click Add API Token
4. Give it a name (e.g., "MCP Server")
5. Copy the generated token

3. Start the Server

Choose your preferred method:

Option A: Using Python (Direct)

python run_server.py

Option B: Using uv (Recommended)

# Install uv if not installed
pip install uv

# Run with uv
uv run python run_server.py

Option C: Using uvx (Run without installing)

# Install uv if not installed
pip install uv

# Run directly without installation
uvx --from . portainer-core-mcp

Option D: Using npm/npx

# Install globally
npm install -g portainer-core-mcp

# Run with npx
npx portainer-core-mcp

Option E: Using the uv wrapper script

# Make executable (if not already)
chmod +x scripts/run-with-uv.py

# Run with uv wrapper
python scripts/run-with-uv.py

Environment Configuration

Using .env File

1. Copy the example file:

   cp .env.example .env
   

2. Edit the file:

   nano .env
   

3. Set your values:

   # Required
   PORTAINER_URL=https://your-portainer-instance.com
   PORTAINER_API_KEY=your-api-key-here
   
   # Optional (with defaults)
   HTTP_TIMEOUT=30
   MAX_RETRIES=3
   LOG_LEVEL=INFO
   DEBUG=false
   

Using Environment Variables

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

# Start server
python run_server.py

Installation Methods

Development Installation

# Clone and install in development mode
git clone <repository-url>
cd portainer-mcp
pip install -e .

# Or with uv
uv pip install -e .

Production Installation

# Install from PyPI (when published)
pip install portainer-core-mcp

# Or with uv
uv pip install portainer-core-mcp

Run Without Installing (uvx)

# Run directly from source without installation
uvx --from . portainer-core-mcp

# Or from PyPI (when published)
uvx portainer-core-mcp

NPM Installation

# Install globally
npm install -g portainer-core-mcp

# Or run without installing
npx portainer-core-mcp

Available Commands

MCP Tools

Once the server is running, the following tools are available:

• authenticate - Login with username/password
• generate_token - Generate API tokens
• get_current_user - Get current 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 configuration
• health_check - Server health status

MCP Resources

• portainer://users - User management data
• portainer://settings - Configuration settings
• portainer://health - Server health status

Testing

Run Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=src

# Run specific test file
python -m pytest tests/test_basic.py

Test Configuration

# Test configuration loading
python -c "
import os
os.environ['PORTAINER_URL'] = 'https://test.com'
os.environ['PORTAINER_API_KEY'] = 'test-key'
from src.portainer_core.config import get_config
config = get_config()
print('✅ Configuration OK')
print(f'URL: {config.portainer_url}')
print(f'API Base: {config.api_base_url}')
"

Troubleshooting

Common Issues

1. Missing API Key Error

   ValueError: PORTAINER_API_KEY must be provided and cannot be empty
   

   Solution: Set the PORTAINER_API_KEY environment variable

2. Invalid URL Error

   ValueError: Invalid Portainer URL
   

   Solution: Ensure PORTAINER_URL includes the protocol (http/https)

3. Python Not Found (npx)

   Error: Python is not installed or not in PATH
   

   Solution: Install Python 3.8+ and ensure it's in your PATH

Debug Mode

Enable debug logging for troubleshooting:

DEBUG=true LOG_LEVEL=DEBUG python run_server.py

Health Check

Test if the server is working:

# Check server health
curl -X POST http://localhost:8000/health

# Or use the health_check tool through MCP

Advanced Usage

Custom Configuration

from portainer_core.config import PortainerConfig

# Create custom config
config = PortainerConfig(
    portainer_url="https://custom.portainer.com",
    portainer_api_key="custom-key",
    http_timeout=60,
    log_level="DEBUG"
)

Programmatic Usage

from portainer_core.server import create_server
import asyncio

async def main():
    server = create_server()
    await server.run()

asyncio.run(main())

Support

• Documentation: See README.md and code comments
• Issues: Report via GitHub Issues
• Configuration: Check .env.example for all options