# Portainer Core MCP Server

This MCP server provides core Portainer functionality by combining user management and teams/RBAC features into a single unified server. It offers comprehensive user, team, and role-based access control 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:
```bash
pip install mcp httpx aiohttp
# Or use the requirements file:
pip install -r requirements.txt
```

2. Configure in Claude Desktop (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "portainer-core": {
      "command": "python",
      "args": ["/path/to/portainer-mcp/portainer_core_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