portainer-mcp/README_EDGE.md

# Portainer Edge MCP Server

This MCP server provides edge computing functionality through Portainer's API, managing edge environments, edge stacks, edge groups, and edge jobs.

## Features

- **Edge Environment Management**: List and monitor edge environments
- **Edge Stack Deployment**: Deploy and manage stacks across edge devices
- **Edge Group Organization**: Create and manage groups of edge endpoints
- **Edge Job Scheduling**: Schedule and run jobs on edge devices
- **Edge Settings Configuration**: Configure global edge settings

## Installation

1. Ensure you have the Portainer MCP servers repository:
   ```bash
   git clone https://github.com/yourusername/portainer-mcp.git
   cd portainer-mcp
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. Configure environment variables:
   ```bash
   cp .env.example .env
   # Edit .env with your Portainer URL and API key
   ```

4. Make the server executable:
   ```bash
   chmod +x portainer_edge_server.py
   ```

## Configuration

Add to your Claude Desktop configuration:

```json
{
  "portainer-edge": {
    "command": "python",
    "args": ["/path/to/portainer-mcp/portainer_edge_server.py"],
    "env": {
      "PORTAINER_URL": "https://your-portainer-instance.com",
      "PORTAINER_API_KEY": "your-api-key"
    }
  }
}
```

## Available Tools

### Edge Environment Management

#### list_edge_environments
List all edge environments.
- **Parameters**:
  - `status` (optional): Filter by status - "connected" or "disconnected"

#### get_edge_environment
Get details of a specific edge environment.
- **Parameters**:
  - `environment_id` (required): Environment ID

#### get_edge_status
Get edge environment status and check-in information.
- **Parameters**:
  - `environment_id` (required): Environment ID

#### generate_edge_key
Generate an edge key for adding new edge agents.
- **Parameters**:
  - `name` (required): Environment name
  - `group_ids` (optional): List of edge group IDs

### Edge Stack Management

#### list_edge_stacks
List all edge stacks.

#### get_edge_stack
Get details of a specific edge stack.
- **Parameters**:
  - `edge_stack_id` (required): Edge Stack ID

#### create_edge_stack
Create a new edge stack.
- **Parameters**:
  - `name` (required): Stack name
  - `stack_content` (required): Stack file content (Docker Compose)
  - `edge_groups` (required): List of edge group IDs
  - `deploy_type` (optional): Deployment type (0: compose, 1: kubernetes)
  - `edge_id_list` (optional): Specific edge IDs for deployment
  - `registries` (optional): List of registry IDs

#### update_edge_stack
Update an existing edge stack.
- **Parameters**:
  - `edge_stack_id` (required): Edge Stack ID
  - `stack_content` (optional): Updated stack content
  - `edge_groups` (optional): Updated edge group IDs
  - `deploy_type` (optional): Updated deployment type

#### delete_edge_stack
Delete an edge stack.
- **Parameters**:
  - `edge_stack_id` (required): Edge Stack ID

### Edge Group Management

#### list_edge_groups
List all edge groups.

#### get_edge_group
Get details of a specific edge group.
- **Parameters**:
  - `edge_group_id` (required): Edge Group ID

#### create_edge_group
Create a new edge group.
- **Parameters**:
  - `name` (required): Group name
  - `dynamic` (optional): Enable dynamic membership (default: false)
  - `tag_ids` (optional): Tag IDs for dynamic groups
  - `endpoints` (optional): Endpoint IDs for static groups

#### update_edge_group
Update an existing edge group.
- **Parameters**:
  - `edge_group_id` (required): Edge Group ID
  - `name` (optional): Updated name
  - `dynamic` (optional): Update dynamic membership
  - `tag_ids` (optional): Updated tag IDs
  - `endpoints` (optional): Updated endpoint IDs

#### delete_edge_group
Delete an edge group.
- **Parameters**:
  - `edge_group_id` (required): Edge Group ID

### Edge Job Management

#### list_edge_jobs
List all edge jobs.

#### get_edge_job
Get details of a specific edge job.
- **Parameters**:
  - `edge_job_id` (required): Edge Job ID

#### create_edge_job
Create a new edge job.
- **Parameters**:
  - `name` (required): Job name
  - `edge_groups` (required): Target edge group IDs
  - `script_content` (required): Script content to execute
  - `recurring` (optional): Enable recurring execution
  - `cron_expression` (optional): Cron expression for scheduling

#### delete_edge_job
Delete an edge job.
- **Parameters**:
  - `edge_job_id` (required): Edge Job ID

### Edge Settings

#### get_edge_settings
Get global edge settings.

#### update_edge_settings
Update global edge settings.
- **Parameters**:
  - `check_in_interval` (optional): Check-in interval in seconds
  - `command_interval` (optional): Command interval in seconds
  - `ping_interval` (optional): Ping interval in seconds
  - `snapshot_interval` (optional): Snapshot interval in seconds
  - `tunnel_server_address` (optional): Tunnel server address

## Usage Examples

### List Edge Environments

```javascript
await use_mcp_tool("portainer-edge", "list_edge_environments", {
  status: "connected"
});
```

### Create Edge Stack

```javascript
await use_mcp_tool("portainer-edge", "create_edge_stack", {
  name: "nginx-edge",
  stack_content: `version: '3'
services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"`,
  edge_groups: ["1", "2"]
});
```

### Create Edge Group

```javascript
// Static group with specific endpoints
await use_mcp_tool("portainer-edge", "create_edge_group", {
  name: "production-edge",
  dynamic: false,
  endpoints: ["10", "11", "12"]
});

// Dynamic group based on tags
await use_mcp_tool("portainer-edge", "create_edge_group", {
  name: "tagged-devices",
  dynamic: true,
  tag_ids: ["1", "3"]
});
```

### Schedule Edge Job

```javascript
await use_mcp_tool("portainer-edge", "create_edge_job", {
  name: "system-update",
  edge_groups: ["1"],
  script_content: "apt update && apt upgrade -y",
  recurring: true,
  cron_expression: "0 2 * * *"  // Daily at 2 AM
});
```

## Edge Computing Concepts

### Edge Environments
Edge environments are remote Docker or Kubernetes environments that connect to Portainer via the Edge Agent. They can be:
- **Connected**: Currently connected and checking in
- **Disconnected**: Not currently reachable

### Edge Stacks
Edge stacks are Docker Compose or Kubernetes deployments that can be deployed to multiple edge environments simultaneously through edge groups.

### Edge Groups
Edge groups organize edge environments for bulk operations:
- **Static Groups**: Manually selected endpoints
- **Dynamic Groups**: Automatically populated based on tags

### Edge Jobs
Edge jobs execute scripts on edge devices:
- **One-time Jobs**: Execute once immediately
- **Recurring Jobs**: Execute on a schedule (cron)

## Testing

Use the provided test script to verify edge functionality:

```bash
python test_edge_server.py
```

This will test:
- Listing edge environments
- Creating and managing edge groups
- Listing edge stacks
- Viewing edge jobs
- Checking edge settings

## Best Practices

1. **Group Organization**: Use edge groups to organize devices by location, purpose, or capability
2. **Stack Templates**: Create reusable stack templates for common deployments
3. **Job Scheduling**: Use recurring jobs for maintenance tasks
4. **Monitoring**: Regularly check edge environment status
5. **Security**: Use proper authentication for edge agents

## Security Considerations

- Edge agents use unique keys for authentication
- Communication is encrypted between edge agents and Portainer
- Edge jobs execute with the permissions of the edge agent
- Limit edge job permissions appropriately
- Regularly rotate edge keys

## Troubleshooting

### Edge Environment Not Connecting
- Check network connectivity from edge device
- Verify edge key is correct
- Check firewall rules
- Review edge agent logs

### Stack Deployment Failures
- Verify stack syntax
- Check image availability on edge devices
- Review resource constraints
- Check edge agent permissions

### Edge Group Issues
- Verify tag configuration for dynamic groups
- Check endpoint assignments for static groups
- Review group membership rules

## Requirements

- Python 3.8+
- Portainer Business Edition 2.19+ (for full edge features)
- Valid Portainer API token
- Edge agents deployed on target devices