Portainer AI Bridge (Portainer MCP Implementation)

Imagine querying the status of your container fleet using plain English.

This is now achievable! Portainer AI Bridge establishes a direct conduit between your chosen artificial intelligence assistant and your managed Portainer instances. Perform administrative tasks concerning users and environments, or execute arbitrary Docker or Kubernetes operational commands entirely via natural language prompts.

Conceptual Framework

Portainer AI Bridge represents an ongoing effort to implement the Model Context Protocol (MCP) specifically tailored for Portainer ecosystems. The core objective is to standardize the integration pathway, enabling Large Language Models (LLMs) and associated services to interface securely with Portainer's comprehensive container management functionalities.

MCP (Model Context Protocol) is an open standard designed to streamline how software furnishes contextual data to LLMs. Analogous to universal standards like USB-C connecting diverse peripherals, MCP standardizes the connection between AI models and various operational data sources and actionable tools.

This specific integration focuses on securely surfacing Portainer environment metadata through the MCP framework, thus empowering AI agents to manage containerized infrastructure using prescribed, secure methodologies.

[!NOTE] Compatibility is strictly tied to certain Portainer release versions. Should your running Portainer version deviate from the expected set, utilizing the --disable-version-check switch permits an attempt at connection bypass. Consult the Version Compatibility Matrix for supported ranges and Bypassing Version Validation for instructions on overriding this safeguard.

Review the Supported Operations Index for granular details regarding feature availability and version alignment.

Disclaimer: This utility remains actively under development.

Operation currently necessitates a valid Portainer administrator API credential.

Acquisition and Setup

Precompiled executables targeting Linux (amd64, arm64) and macOS (arm64) are accessible on the Latest Release Artifacts Page. Select the appropriate compressed archive corresponding to your target operating system and processor architecture within the "Assets" listing.

Downloading the Package: Direct download via the release page is typical. Alternatively, curl can be employed. Below is an example for macOS (ARM64), targeting release v0.2.0:

bash

Adjust version tag and architecture as necessary

curl -Lo portainer-mcp-v0.2.0-darwin-arm64.tar.gz https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-darwin-arm64.tar.gz

(Binaries for Linux AMD64 are also provisioned on the release page.)

(Optional but Strongly Advised) Integrity Check: First, retrieve the accompanying .md5 checksum file from the release page. Example for macOS (ARM64) v0.2.0:

bash

Fetch the checksum file (update version/arch)

curl -Lo portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5 https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5

Execute verification (expected output should match the .md5 file content)

if [ "$(md5 -q portainer-mcp-v0.2.0-darwin-arm64.tar.gz)" = "$(cat portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5)" ]; then echo "Integrity Verified"; else echo "Verification Failed"; fi

(For Linux environments, utilize md5sum -c <checksum_file_name>.md5) Successful execution resulting in "Integrity Verified" confirms the file has not been corrupted.

Decompressing the Archive:

bash

Adjust filename based on your downloaded version/OS/architecture

tar -xzf portainer-mcp-v0.2.0-darwin-arm64.tar.gz

This action extracts the primary portainer-mcp executable.

Relocating the Executable: Move the binary to a directory listed in your system's $PATH (e.g., /usr/local/bin) or record its current path for the subsequent configuration stage.

Deployment Protocol

When integrating with an assistant platform like Claude Desktop, configure it using a structure resembling this:

{ "mcpServers": { "portainer": { "command": "/path/to/portainer-mcp", "args": [ "-server", "[IP]:[PORT]", "-token", "[TOKEN]", "-tools", "/tmp/tools.yaml" ] } } }

Substitute [IP], [PORT], and [TOKEN] with the precise network address, listening port, and administrative access credential for your Portainer instance.

[!NOTE] By default, the application attempts to locate or generate the "tools.yaml" definition file in the same directory as the executable. If this file is absent, it is created with default tool definitions. Adjusting this path via the -tools argument is critical, especially when utilizing AI environments (like Claude) that impose restrictions on write operations within the execution context.

Bypassing Version Validation

Ordinarily, the utility validates the connected Portainer server version against its internal compatibility list and halts startup upon mismatch. To force a connection attempt despite version disparity, include the -disable-version-check argument:

{ "mcpServers": { "portainer": { "command": "/path/to/portainer-mcp", "args": [ "-server", "[IP]:[PORT]", "-token", "[TOKEN]", "-disable-version-check" ] } } }

[!WARNING] Circumventing version validation carries a risk of unpredictable operational anomalies or complete failure due to unforeseen API revisions between Portainer versions. Partial or total functionality loss is possible with unsupported server targets.

When this flag is active: - Startup sequence skips Portainer server version verification. - Features might behave erratically due to version-specific API divergence. - Newer Portainer releases might trigger execution errors from API expectation mismatches. - Older Portainer versions might lack required API endpoints.

This override is beneficial when: - You operate a Portainer release newer than officially supported by the current MCP bridge version. - You wish to experimentally test compatibility with an older Portainer instance.

Tool Definition Customization

Tool definitions are intrinsically bundled within the binary initially. The program will materialize this file at its standard location if it does not exist.

You gain control over these definitions by pointing to an external YAML file using the -tools option:

{ "mcpServers": { "portainer": { "command": "/path/to/portainer-mcp", "args": [ "-server", "[IP]:[PORT]", "-token", "[TOKEN]", "-tools", "/path/to/custom/tools.yaml" ] } } }

The reference default tool definitions reside at internal/tooldef/tools.yaml in the source repository. Modifying the descriptive text associated with tools allows fine-tuning how AI agents interpret and select their invocation. You retain the option to deactivate specific tools entirely.

[!WARNING] Crucially, maintain the exact naming convention for tool identifiers and their mandated parameter structures (descriptions are the only safe element to alter). Deviation will result in registration failure and render the tools inert.

Egress Control (Read-Only Mode)

For environments prioritizing strict data integrity, the utility supports a read-only operational mode. This configuration completely neutralizes all write capabilities, restricting the AI to observation-only actions on Portainer assets.

Activate read-only status by appending the -read-only argument:

{ "mcpServers": { "portainer": { "command": "/path/to/portainer-mcp", "args": [ "-server", "[IP]:[PORT]", "-token", "[TOKEN]", "-read-only" ] } } }

When operating in read-only restriction: - Only query operations (list, retrieve) are exposed to the language model. - All mutation tools (create, modify, erase) are suppressed from the exposed toolset. - The Docker API proxy utility is disabled. - The Kubernetes API proxy utility is disabled.

Version Compatibility Matrix

This integration is version-locked to specific Portainer releases. The startup validation step ensures alignment; failure to match results in termination.

Portainer AI Bridge Version	Compatible Portainer Version
0.1.0	2.28.1
0.2.0	2.28.1
0.3.0	2.28.1
0.4.0	2.29.2
0.4.1	2.29.2
0.5.0	2.30.0
0.6.0	2.31.2

[!NOTE] For connectivity to unsupported Portainer versions, reference the Bypassing Version Validation section for guidance and associated caveats.

Supported Operations Index

The ensuing table catalogs the functionalities currently exposed (as of the latest Bridge release) via the MCP interface:

Resource	Operation	Rationale	Initial Version
Environments
	ListEnvironments	Retrieve all accessible environments	0.1.0
	UpdateEnvironmentTags	Modify descriptive metadata tags on an environment	0.1.0
	UpdateEnvironmentUserAccesses	Adjust user permissions linked to an environment	0.1.0
	UpdateEnvironmentTeamAccesses	Adjust team access rights for an environment	0.1.0
Environment Groups (Edge Groups)
	ListEnvironmentGroups	Enumerate defined environment groupings	0.1.0
	CreateEnvironmentGroup	Provision a new edge group	0.1.0
	UpdateEnvironmentGroupName	Rename an existing edge group	0.1.0
	UpdateEnvironmentGroupEnvironments	Modify the environment membership of a group	0.1.0
	UpdateEnvironmentGroupTags	Modify edge group metadata tags	0.1.0
Access Groups (Endpoint Groups)
	ListAccessGroups	List endpoint grouping structures	0.1.0
	CreateAccessGroup	Establish a new endpoint group	0.1.0
	UpdateAccessGroupName	Rename an existing endpoint group	0.1.0
	UpdateAccessGroupUserAccesses	Modify user permissions within an endpoint group	0.1.0
	UpdateAccessGroupTeamAccesses	Modify team permissions within an endpoint group	0.1.0
	AddEnvironmentToAccessGroup	Associate an environment with a group	0.1.0
	RemoveEnvironmentFromAccessGroup	Dissociate an environment from a group	0.1.0
Stacks (Edge Stacks)
	ListStacks	Retrieve all deployed stacks	0.1.0
	GetStackFile	Fetch the underlying compose definition for a stack	0.1.0
	CreateStack	Deploy a new Docker stack	0.1.0
	UpdateStack	Modify an active Docker stack configuration	0.1.0
Tags
	ListEnvironmentTags	List all tags applied across environments	0.1.0
	CreateEnvironmentTag	Register a new environment-specific tag	0.1.0
Teams
	ListTeams	Enumerate established teams	0.1.0
	CreateTeam	Form a new team entity	0.1.0
	UpdateTeamName	Modify a team's designated name	0.1.0
	UpdateTeamMembers	Modify the roster of team members	0.1.0
Users
	ListUsers	Retrieve the registry of system users	0.1.0
	UpdateUser	Modify an existing user's profile details	0.1.0
	GetSettings	Query the global Portainer instance configuration	0.1.0
Docker
	DockerProxy	Forward arbitrary Docker API requests	0.2.0
Kubernetes
	KubernetesProxy	Forward arbitrary Kubernetes API requests	0.3.0
	getKubernetesResourceStripped	Forward GET K8s requests, auto-pruning excessive metadata fields	0.6.0

Development Guidelines

Source Code Metrics

A utility script, cloc.sh, is present in the repository root to compute source line counts and related statistics using the cloc utility. Ensure cloc is installed (e.g., via sudo apt install cloc or brew install cloc).

Execute the script from the repository root for the default summarized output:

bash ./cloc.sh

Refer to the introductory comments within cloc.sh for flags that allow retrieval of specific measurement aggregates.

Prompt Token Cost Estimation

To approximate the token consumption of your current tool definitions within prompts, utilize the bundled Go program alongside a shell script designed to interface with the Anthropic API token counting endpoint.

1. Artifact Generation (Tools JSON): First, employ the token-count Go program to translate your YAML tool specifications into the JSON payload format mandated by the Anthropic API. Execute this from the repository root:

bash

Assume input YAML is at internal/tooldef/tools.yaml

Specify your desired output JSON location

go run ./cmd/token-count -input internal/tooldef/tools.yaml -output .tmp/tools.json

This command parses the input YAML tool definitions and writes a JSON array detailing each tool's name, description, and input_schema to the specified destination file.

2. API Query Execution: Subsequently, leverage the token.sh script to transmit these tool definitions alongside a representative sample message to the Anthropic service. A valid Anthropic API key is mandatory.

bash

Prerequisite: jq must be installed

Replace sk-ant-xxxxxxxx with your active Anthropic API authentication key

Ensure .tmp/tools.json points to the file generated in Step 1

./token.sh -k sk-ant-xxxxxxxx -i .tmp/tools.json

The script will output the resulting JSON payload from the Anthropic API, explicitly detailing the estimated token expenditure for the supplied toolset and message within the usage.input_tokens field.

This methodical approach allows for precise comprehension of the token overhead introduced by the toolset provided to the language model.

WIKIPEDIA: Google Cloud Platform (GCP) represents a comprehensive suite of distributed computing utilities offered by Google, encompassing modular services such as computation, persistent data storage, advanced data analysis, and machine learning capabilities, complemented by integrated management utilities. This infrastructure mirrors the foundational architecture Google employs internally for high-volume consumer products like Google Search, Gmail, and Google Docs, as documented by Verma et al. Service enrollment mandates verified credit card or bank account credentials. Google Cloud Platform furnishes Infrastructure as a Service (IaaS), Platform as a Service (PaaS), and serverless execution paradigms. In the second quarter of 2008, Google unveiled App Engine, a foundational platform facilitating the development and hosting of web applications within Google-operated data centers, marking the corporation's inaugural cloud offering. General availability commenced in late 2011. Following App Engine's introduction, Google systematically expanded its portfolio of associated cloud services. Google Cloud Platform constitutes a segment of the broader Google Cloud umbrella, which integrates the public cloud infrastructure of GCP with Google Workspace (formerly G Suite), enterprise editions of Android and ChromeOS, and specialized Application Programming Interfaces (APIs) for advanced mapping and machine learning functions. Since at least 2022, official Google documentation has standardized the nomenclature, asserting "Google Cloud" as the updated designation for "Google Cloud Platform," which can occasionally lead to terminological ambiguity.

== Principal Offerings == Google catalogs upwards of 100 distinct products under the Google Cloud branding. Key services are enumerated below.

=== Computation Resources === App Engine – A PaaS environment for deploying applications built using Java, PHP, Node.js, Python, C#, .Net, Ruby, and Go. Compute Engine – An IaaS layer supporting the execution of virtual machines running both Microsoft Windows and Linux operating systems. Google Kubernetes Engine (GKE) or GKE on-prem (available via Anthos) – A container orchestration service built upon Kubernetes technology. Cloud Functions – A Functions as a Service (FaaS) offering for executing event-driven code segments written in Node.js, Java, Python, or Go. Cloud Run – A container execution environment leveraging Knative. It is offered as a fully managed service or integrated with Anthos. Currently supports unified management across GCP, AWS, and VMware environments.

=== Data Persistence and Databases === Cloud Storage – Scalable object storage featuring integrated edge caching for unstructured data repositories. Cloud SQL – A managed Database as a Service supporting MySQL, PostgreSQL, and Microsoft SQL Server. Cloud Bigtable – A managed, high-throughput NoSQL database service. Cloud Spanner – A globally distributed, strongly consistent, relational database service designed for horizontal scaling. Cloud Datastore – A NoSQL database optimized for web and mobile application backends. Persistent Disk – Block storage volumes provisioned for Compute Engine virtual machines. Cloud Memorystore – Managed in-memory caching services based on Redis and Memcached protocols. Local SSD: High-speed, ephemeral, local block storage attachments. Filestore: Managed, high-performance file storage solutions for Google Cloud consumers. AlloyDB: A fully managed database compatible with PostgreSQL standards.

=== Network Infrastructure ===

VPC – Virtual Private Cloud, providing isolated network segments.