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:

   git clone https://github.com/yourusername/portainer-mcp.git
   cd portainer-mcp
   

2. Install dependencies:

   pip install mcp httpx aiohttp
   # Or use the requirements file:
   pip install -r requirements.txt
   

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your Portainer URL and API key
   

4. Make the server executable:

   chmod +x portainer_edge_server.py
   

Configuration

Add to your Claude Desktop configuration:

{
  "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

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

Create Edge Stack

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

// 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

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:

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