portainer-mcp/README_MERGED.md

Portainer Unified MCP Server

This MCP server combines portainer-core and portainer-teams functionality into a single unified server, providing comprehensive user, team, and RBAC management for Portainer Business Edition.

Features

User Management (from portainer-core)

• Authentication & Session Management
  • Test connection to Portainer
  • API token validation
• User CRUD Operations
  • List all users
  • Create new users with role assignment
  • Update user passwords and roles
  • Delete users

Teams Management (from portainer-teams)

• Team Operations
  • List all teams
  • Create new teams with optional leaders
  • Delete teams
• Team Membership
  • Add users to teams
  • Remove users from teams
  • Bulk membership operations

RBAC Management

• Role Management
  • List available roles with descriptions
  • View role priorities and permissions
• Resource Access Control
  • List all resource controls
  • Create resource-specific access controls
  • Configure public/private access
  • Set user and team permissions

Settings Management

• System Configuration
  • Get current Portainer settings
  • Update security settings
  • Configure user permissions

Installation

1. Install Python dependencies:

cd /Users/adelorenzo/repos/portainer-mcp
.venv/bin/pip install mcp httpx

2. Configure in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "portainer": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/merged_mcp_server.py"],
      "env": {
        "PORTAINER_URL": "https://your-portainer-instance.com",
        "PORTAINER_API_KEY": "your-api-key",
        "MCP_MODE": "true"
      }
    }
  }
}

3. Restart Claude Desktop

Available Tools

User Management

• test_connection - Test connection to Portainer
• get_users - List all users with their roles
• create_user - Create a new user (username, password, role)
• update_user - Update user password or role
• delete_user - Delete a user by ID

Teams Management

• get_teams - List all teams
• create_team - Create a new team with optional leaders
• add_team_members - Add users to a team
• remove_team_members - Remove users from a team
• delete_team - Delete a team by ID

RBAC Management

• get_roles - List available roles and their descriptions
• get_resource_controls - List all resource access controls
• create_resource_control - Create access control for a resource

Settings

• get_settings - Get current Portainer settings
• update_settings - Update Portainer security settings

Role Types

The server supports three role types:

• Administrator - Full system access
• StandardUser - Regular user access
• ReadOnlyUser - Read-only access

Example Usage

Create a user and add to team:

1. Use "create_user" with username: "john", password: "secure123", role: "StandardUser"
2. Use "get_users" to find John's user ID
3. Use "create_team" with name: "DevOps Team"
4. Use "get_teams" to find the team ID
5. Use "add_team_members" with the team ID and John's user ID

Set up resource access control:

1. Use "create_resource_control" with:
   - resource_id: "container_id_here"
   - resource_type: "container"
   - teams: [{"team_id": 1, "access_level": "read"}]
   - administrators_only: false

Compatibility

• Supports both old (integer) and new (string) role formats
• Works with Portainer Business Edition 2.30.x+
• Handles API version differences automatically

Security Notes

• API key is required for all operations
• HTTPS is recommended (SSL verification disabled for development)
• Tokens should be rotated regularly
• All operations respect Portainer's RBAC system