Adolfo Delorenzo
7a1abbe243
- Implement comprehensive edge computing functionality - Add edge environment management (list, get, status, generate keys) - Add edge stack operations (list, get, create, update, delete) - Add edge group management (list, get, create, update, delete) - Add edge job scheduling (list, get, create, delete) - Add edge settings configuration (get, update) - Create test scripts for edge API validation - Add comprehensive README documentation for edge server - Include nginx stack creation script from earlier testing 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
312 lines
8.1 KiB
Markdown
312 lines
8.1 KiB
Markdown
# 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 |