portainer-mcp/README_ENVIRONMENTS.md

# Portainer Environments MCP Server

This MCP server provides comprehensive environment and endpoint management functionality for Portainer Business Edition.

## Features

### Environment Management
- **List and View Environments**
  - List all environments with status and type
  - Get detailed information about specific environments
  - View environment statistics and Docker/Kubernetes info

- **Create Environments**
  - Docker environments (local and remote)
  - Kubernetes clusters
  - Docker Swarm clusters
  - Edge Agent environments
  - Support for TLS configuration

- **Update and Delete**
  - Update environment settings and URLs
  - Change group assignments
  - Delete environments safely

### Environment Organization
- **Environment Groups**
  - Create and manage environment groups
  - Organize environments by purpose or location
  - Update group names and descriptions
  - Delete unused groups

- **Tags Management**
  - Create tags for categorizing environments
  - List all available tags
  - Delete unused tags
  - Assign multiple tags to environments

### Access Control
- **Team Associations**
  - Associate environments with teams
  - Set read/write access levels
  - Bulk update team permissions

### Edge Computing
- **Edge Agent Deployment**
  - Generate Edge keys for remote deployments
  - Get deployment scripts automatically
  - Support for Edge environment groups

## Installation

1. Ensure Python dependencies are installed:
```bash
cd /Users/adelorenzo/repos/portainer-mcp
.venv/bin/pip install mcp httpx
```

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

### Environment Operations
- `list_environments` - List all environments with pagination support
- `get_environment` - Get detailed information about an environment
- `create_docker_environment` - Create a new Docker environment
- `create_kubernetes_environment` - Create a new Kubernetes environment
- `update_environment` - Update environment settings
- `delete_environment` - Delete an environment
- `get_environment_status` - Get real-time status and statistics

### Access Control
- `associate_environment` - Associate environments with teams and set permissions

### Organization
- `list_environment_groups` - List all environment groups
- `create_environment_group` - Create a new environment group
- `update_environment_group` - Update group information
- `delete_environment_group` - Delete an environment group

### Tags
- `list_tags` - List all available tags
- `create_tag` - Create a new tag
- `delete_tag` - Delete a tag

### Edge Computing
- `generate_edge_key` - Generate Edge agent deployment script

## Environment Types

The server supports these environment types:
- **Docker** - Standard Docker environments
- **Docker Swarm** - Swarm cluster management
- **Kubernetes** - Kubernetes cluster management
- **Azure ACI** - Azure Container Instances
- **Edge Agent** - Remote Edge deployments

## Example Usage

### Create a Docker environment:
```
Use "create_docker_environment" with:
- name: "Production Docker"
- url: "tcp://docker-prod.example.com:2375"
- public_url: "https://docker-prod.example.com"
- tls: true
- tags: ["production", "docker"]
```

### Create a Kubernetes environment:
```
Use "create_kubernetes_environment" with:
- name: "K8s Production"
- url: "https://k8s-api.example.com:6443"
- bearer_token: "your-bearer-token"
- tls_skip_verify: false
```

### Deploy an Edge agent:
```
1. Use "generate_edge_key" with name: "Remote Site 1"
2. Copy the generated deployment command
3. Run the command on the remote Docker host
```

### Organize environments:
```
1. Use "create_environment_group" with name: "Production Servers"
2. Use "create_tag" with name: "critical"
3. Use "update_environment" to assign the group and tags
```

## API Compatibility

This server handles both old and new Portainer API endpoints:
- New API (2.19.x+): `/environments`
- Old API (pre-2.19): `/endpoints`

The server automatically tries both endpoints for compatibility.

## Security Notes

- API key is required for all operations
- HTTPS is recommended (SSL verification disabled for development)
- Team associations respect Portainer's RBAC system
- Edge keys should be kept secure

## Troubleshooting

### Common Issues

**Environment shows as "down":**
- Check network connectivity to the Docker/Kubernetes API
- Verify TLS certificates if using secure connections
- Ensure the API endpoint URL is correct

**Cannot create environment:**
- Verify the URL format (tcp:// for Docker, https:// for Kubernetes)
- Check if the environment name already exists
- Ensure proper authentication credentials

**Edge agent not connecting:**
- Verify the Edge key is correct
- Check firewall rules for outbound connections
- Ensure Docker is running on the Edge device

## Docker URL Formats

- **Local Docker:** `unix:///var/run/docker.sock`
- **Remote Docker (TCP):** `tcp://hostname:2375`
- **Remote Docker (TLS):** `tcp://hostname:2376`
- **Docker Desktop (Mac):** `unix:///$HOME/.docker/run/docker.sock`
- **Docker Desktop (Windows):** `npipe:////./pipe/docker_engine`

## Kubernetes Authentication

For Kubernetes environments, you can use:
- **Bearer Token:** Service account token
- **Client Certificate:** Upload certificate files (in UI)
- **Kubeconfig:** Import kubeconfig file (in UI)