---
title: "Connect Portainer to Claude: Orchestrate Helm Charts and GitOps"
slug: connect-portainer-to-claude-orchestrate-helm-charts-and-gitops
date: 2026-07-25
author: Roopendra Talekar
categories: ["AI & Agents"]
excerpt: "Learn how to connect Portainer to Claude using a managed MCP server. This step-by-step guide covers configuration, tool calling, and orchestrating GitOps."
tldr: "Connect Portainer to Claude via Truto's managed MCP server to orchestrate Kubernetes clusters, automate GitOps workflows, and execute infrastructure commands securely using natural language."
canonical: https://truto.one/blog/connect-portainer-to-claude-orchestrate-helm-charts-and-gitops/
---

# Connect Portainer to Claude: Orchestrate Helm Charts and GitOps


If your team uses ChatGPT, check out our guide on [connecting Portainer to ChatGPT](https://truto.one/connect-portainer-to-chatgpt-manage-kubernetes-clusters-and-stacks/) or explore our broader architectural overview on [connecting Portainer to AI Agents](https://truto.one/connect-portainer-to-ai-agents-monitor-nodes-and-manage-edge-jobs/).

Giving a Large Language Model (LLM) read and write access to your container orchestration infrastructure is a massive engineering challenge. You are dealing with highly privileged operations - deploying Helm charts, draining Kubernetes nodes, and restarting pods. To do this safely, you need a secure translation layer between Claude's tool calls and Portainer's REST APIs. You can either spend weeks building, hosting, and maintaining custom integration code, or you can use a managed platform like Truto to dynamically generate a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/).

This guide breaks down exactly how to use Truto to generate a secure, [managed MCP server for Portainer](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/), connect it natively to Claude Desktop, and orchestrate complex GitOps and Kubernetes workflows using natural language.

## The Engineering Reality of the Portainer API

A custom MCP server is a self-hosted integration layer that translates an LLM's JSON-RPC 2.0 tool calls into REST API requests. While the [open MCP standard](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/) provides a predictable way for models to discover tools, implementing it against [Portainer's API surface](https://truto.one/connect-portainer-to-ai-agents-monitor-nodes-and-manage-edge-jobs/) requires navigating several domain-specific quirks.

If you decide to build a custom MCP server for Portainer, you own the entire API lifecycle. Here are the specific challenges you will face:

**Environment-Scoped Routing**
Portainer acts as a centralized management plane for Docker, Kubernetes, Nomad, and Edge environments. As a result, almost every administrative API endpoint requires an `endpointId` or `kubernete_id` in the path or query parameters. If an LLM misinterprets its context and passes the wrong environment ID, it could drain a node in production instead of staging. Your custom MCP server has to implement strict validation logic to ensure models map their intent to the correct environment identifiers before passing payloads upstream.

**Raw Upstream Schema Passthrough**
Portainer does not strictly normalize Kubernetes API responses. When you request node metrics or pod descriptions, Portainer frequently passes through raw, deeply nested Kubernetes shapes (like `v1beta1.NodeMetricsList`). If you handwrite your MCP tool definitions, you are responsible for maintaining massive JSON Schemas that reflect these upstream Kubernetes API versions. Truto derives tool schemas dynamically from comprehensive documentation records, ensuring the LLM understands exactly what nested data structures it is dealing with.

**Rate Limits and Concurrency**
While Portainer sits in front of your clusters, querying it too aggressively can strain both Portainer's database and the underlying Kubernetes API servers it proxies. Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns HTTP 429, Truto passes that error to the caller. Truto normalizes upstream rate limit info into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF spec. The caller - whether that is your application logic or a sophisticated agent loop - is responsible for implementing retry and exponential backoff strategies.

Instead of building out OAuth token lifecycles, KV storage for routing, and massive OpenAPI schema translations from scratch, you can use Truto to handle the boilerplate. Truto exposes Portainer's API as ready-to-use MCP tools, allowing you to focus on agent orchestration.

## How to Generate a Portainer MCP Server

Truto creates MCP servers dynamically based on your connected integrations. Tool generation is documentation-driven - Truto automatically parses Portainer's resources, injects pagination instructions, standardizes authentication, and exposes them over a secure JSON-RPC 2.0 endpoint.

You can generate this server via the Truto UI or programmatically via the API.

### Option 1: Via the Truto UI

If you are setting up an internal tool or testing a workflow, the UI is the fastest path.

1. Navigate to the **Integrated Accounts** page in your Truto dashboard and select your connected Portainer instance.
2. Click the **MCP Servers** tab.
3. Click **Create MCP Server**.
4. Configure the server. You can restrict it to specific HTTP methods (e.g., `read` only) or specific resource tags to limit the LLM's blast radius.
5. Click Create and copy the generated MCP server URL (e.g., `https://api.truto.one/mcp/a1b2c3...`).

### Option 2: Via the Truto API

For production workflows, you can provision MCP servers programmatically. This is ideal for generating short-lived servers or scoping access per user.

Make an authenticated `POST` request to the Truto API:

```bash
curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portainer DevOps Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'
```

The response contains the secure token URL. The URL includes a cryptographically hashed token that authenticates requests back to your specific Portainer environment. 

## How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you need to connect it to your Claude client. You can do this via the Claude interface or by modifying your local configuration file.

### Option 1: Via the Claude UI

If your Claude plan supports UI-based custom connectors (e.g., Claude for Enterprise or Team tiers):

1. Open Claude and navigate to **Settings**.
2. Locate the **Integrations** or **Connectors** section.
3. Click **Add MCP Server**.
4. Paste the Truto MCP URL you generated earlier and save.

Claude will immediately ping the `/initialize` endpoint, complete the JSON-RPC handshake, and populate its context with the available Portainer tools.

### Option 2: Via Manual Configuration File (Claude Desktop)

If you are using Claude Desktop for local agent development, you can register the server via your `claude_desktop_config.json` file. Because [Truto's MCP servers](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/) are served over standard HTTP (SSE), you will use the official `@modelcontextprotocol/server-sse` transport proxy to handle the connection.

Locate your Claude Desktop config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Add the Portainer server configuration:

```json
{
  "mcpServers": {
    "portainer-devops": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN_HERE"
      ]
    }
  }
}
```

Restart Claude Desktop. The model now has direct, authenticated access to your Portainer infrastructure.

## Hero Tools for Portainer

Truto exposes dozens of Portainer operations as AI-ready tools. Here are the highest-leverage tools for automating orchestration and GitOps. 

### Generate Kubeconfigs
**Tool:** `list_all_portainer_kubernetes_configs`
Generates a valid kubeconfig file allowing external clients to communicate with the Kubernetes API server managed by Portainer. This is critical for agents that need to spawn secondary local processes (like `kubectl`) to interact with a cluster.

> "Generate a kubeconfig for the production Kubernetes environment (ID: 4). I need to pass this config to a local script to debug a networking issue."

### Install Helm Charts
**Tool:** `create_a_portainer_kubernetes_helm`
Installs a new Helm release into a specific Kubernetes environment and namespace. The model can provide the chart repository, name, and values payload directly.

> "Deploy the latest Redis Helm chart from the Bitnami repository into the 'cache' namespace on environment ID 2. Set the architecture to standalone."

### Drain Kubernetes Nodes
**Tool:** `create_a_portainer_node_drain`
Safely evicts all pods from a target Kubernetes node, preparing it for maintenance or removal. This is a powerful administrative tool for infrastructure lifecycle management.

> "Drain the Kubernetes node named 'worker-pool-3-node-1' in environment ID 5. We need to take it offline for kernel patching."

### Manage GitOps Workflows
**Tool:** `create_a_portainer_stack_git`
Updates the Git configuration for an existing Portainer stack. This tool allows the model to modify repository references, branches, and auto-update settings for GitOps deployments.

> "Update the Git configuration for stack ID 12. Point it to the 'staging' branch instead of 'main' and ensure auto-updates are enabled."

### Monitor Live Node Metrics
**Tool:** `list_all_portainer_metrics_nodes`
Retrieves live metrics across all nodes in a Portainer Kubernetes environment. The LLM can use this data to calculate utilization, identify bottlenecks, and recommend scaling actions.

> "Fetch the live metrics for all nodes in cluster ID 3. Tell me which node has the highest memory utilization right now."

### Audit Namespace Events
**Tool:** `portainer_kubernete_namespaces_list_events`
Lists recent Kubernetes events for a specific namespace. Essential for root-cause analysis when pods are failing to schedule or crashing in loops.

> "Get the recent Kubernetes events for the 'frontend-prod' namespace in environment 1. Summarize any Warning or Error events from the last 15 minutes."

*(Note: This is just a curated selection of high-value operations. Truto exposes endpoints for edge jobs, user management, registries, and more. For the complete tool inventory and schema definitions, visit the [Portainer integration page](https://truto.one/integrations/detail/portainer).)*

## Workflows in Action

By chaining these tools together, Claude transitions from a simple chat interface into a capable Site Reliability Engineer (SRE). Here is how complex Portainer workflows operate in practice.

### Workflow 1: Incident Response and Node Eviction

A monitoring alert fires indicating high CPU utilization on a specific Kubernetes worker node. You ask Claude to investigate and mitigate the issue.

> "Node worker-app-02 in cluster ID 4 is throwing high CPU alerts. Check the live metrics. If the CPU usage is above 90%, drain the node safely so we can investigate."

1. **`list_all_portainer_metrics_nodes`**: Claude calls the metrics API, passing `kubernete_id: 4`. It parses the returned `v1beta1.NodeMetricsList`, isolating the CPU usage for `worker-app-02`. 
2. **Analysis**: Claude determines that the node is indeed operating at 94% CPU capacity, meeting your threshold criteria.
3. **`create_a_portainer_node_drain`**: Claude executes the drain command, passing the environment ID and the specific node name. Portainer coordinates with the Kubernetes API to gracefully evict the pods.

The user gets back a concise summary: *"I verified that worker-app-02 is running at 94% CPU. I have initiated a safe node drain to evict its pods. The node is now cordoned and draining."*

```mermaid
sequenceDiagram
  participant User as User
  participant Claude as Claude Desktop
  participant MCP as Truto MCP Server
  participant Portainer as Portainer API

  User->>Claude: "Check metrics and drain node if CPU > 90%"
  Claude->>MCP: Call list_all_portainer_metrics_nodes
  MCP->>Portainer: GET /api/endpoints/4/kubernetes/metrics/nodes
  Portainer-->>MCP: Returns NodeMetricsList
  MCP-->>Claude: JSON data
  Claude->>Claude: Analyzes CPU capacity
  Claude->>MCP: Call create_a_portainer_node_drain
  MCP->>Portainer: POST /api/endpoints/4/kubernetes/nodes/worker-app-02/drain
  Portainer-->>MCP: 204 No Content
  MCP-->>Claude: Success
  Claude-->>User: "Node drained successfully"
```

### Workflow 2: GitOps Stack Reconfiguration

You are moving a service from a testing branch into a staging environment and want to reconfigure your Portainer stack dynamically.

> "We need to deploy the latest release of our payment service. Update the Git configuration for stack ID 28 to point to the 'release-v2' branch and trigger a redeployment."

1. **`get_single_portainer_stack_by_id`**: Claude first checks the current configuration of stack 28 to ensure it exists and grabs its current baseline state.
2. **`create_a_portainer_stack_git`**: Claude updates the stack's Git reference, modifying the `RefName` payload to target `refs/heads/release-v2`.
3. **`portainer_git_redeploys_bulk_update`**: With the Git reference updated, Claude calls the redeploy endpoint to force Portainer to pull the latest compose or manifest files from the new branch and apply them to the cluster.

The user gets back: *"Stack 28 has been successfully updated to track the 'release-v2' branch and the redeployment has been triggered. The stack is now syncing."*

## Security and Access Control

Exposing orchestration APIs to an LLM requires strict boundary setting. Truto provides several mechanisms to lock down MCP server capabilities at the infrastructure level.

*   **Method Filtering:** When creating the server, use `config.methods = ["read"]` to restrict the token entirely. The LLM will only see `get` and `list` operations, ensuring it can fetch metrics but physically cannot execute `delete` or `create` commands.
*   **Tag Filtering:** Limit the server's scope by functional area. By passing `config.tags = ["kubernetes"]`, the MCP server will omit all tools related to Docker Swarm, users, or edge computing, reducing the LLM's attack surface.
*   **Required API Token Auth:** By default, anyone with the MCP URL can interact with the server. By setting `require_api_token_auth: true`, you force the client to pass a valid Truto API token in the headers. This ensures only authenticated internal team members can trigger Portainer actions via the agent.
*   **Automatic Expiry:** Use the `expires_at` property to generate short-lived MCP servers. If you need to give a contractor an AI agent with temporary access to audit cluster logs, you can set the server to destruct automatically after 48 hours.

## Shifting from Chatbots to Infrastructure Operators

Integrating Portainer with Claude transforms how engineering teams manage containerized workloads. You are no longer writing one-off bash scripts to parse nested `kubectl` output or navigating through nested UI panels to drain nodes. By providing Claude with an MCP server, you turn the model into a context-aware infrastructure operator.

Building this connectivity layer from scratch requires dealing with OAuth, rate limits, and massive schema translation logic. Truto's dynamic MCP server generation abstracts this away entirely. You connect your Portainer account, generate the URL, and start executing GitOps workflows in minutes.

:::cta{buttonText="Talk to us" buttonUrl="https://cal.com/truto/partner-with-truto"} 
Want to connect Portainer to your AI agents without the integration headache? Truto handles the authentication, schema mapping, and MCP server hosting for you.
:::