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:

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

2. Configure in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "portainer-environments": {
      "command": "python",
      "args": ["/path/to/portainer-mcp/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)