Portainer MCP

1# Portainer MCP
2[![Go Report Card](https://goreportcard.com/badge/github.com/portainer/portainer-mcp)](https://goreportcard.com/report/github.com/portainer/portainer-mcp)
3![coverage](https://raw.githubusercontent.com/portainer/portainer-mcp/badges/.badges/main/coverage.svg)
4 
5Ever wished you could just ask Portainer what's going on?
6 
7Now you can! Portainer MCP connects your AI assistant directly to your Portainer environments. Manage Portainer resources such as users and environments, or dive deeper by executing any Docker or Kubernetes command directly through the AI.
8 
9![portainer-mcp-demo](https://downloads.portainer.io/mcp-demo5.gif)
10 
11## Overview
12 
13Portainer MCP is a work in progress implementation of the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) for Portainer environments. This project aims to provide a standardized way to connect Portainer's container management capabilities with AI models and other services.
14 
15MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs (Large Language Models). Similar to how USB-C provides a standardized way to connect devices to peripherals, MCP provides a standardized way to connect AI models to different data sources and tools.
16 
17This implementation focuses on exposing Portainer environment data through the MCP protocol, allowing AI assistants and other tools to interact with your containerized infrastructure in a secure and standardized way.
18 
19> [!NOTE]
20> This tool is designed to work with specific Portainer versions. If your Portainer version doesn't match the supported version, you can use the `--disable-version-check` flag to attempt connection anyway. See [Portainer Version Support](#portainer-version-support) for compatible versions and [Disable Version Check](#disable-version-check) for bypass instructions.
21 
22See the [Supported Capabilities](#supported-capabilities) sections for more details on compatibility and available features.
23 
24*Note: This project is currently under development.*
25 
26It is currently designed to work with a Portainer administrator API token.
27 
28## Installation
29 
30You can download pre-built binaries for Linux (amd64, arm64) and macOS (arm64) from the [**Latest Release Page**](https://github.com/portainer/portainer-mcp/releases/latest). Find the appropriate archive for your operating system and architecture under the "Assets" section.
31 
32**Download the archive:**
33You can usually download this directly from the release page. Alternatively, you can use `curl`. Here's an example for macOS (ARM64) version `v0.2.0`:
34 
35```bash
36# Example for macOS (ARM64) - adjust version and architecture as needed
37curl -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
38```
39 
40(Linux AMD64 binaries are also available on the release page.)
41 
42**(Optional but recommended) Verify the checksum:**
43First, download the corresponding `.md5` checksum file from the release page.
44Example for macOS (ARM64) `v0.2.0`:
45 
46```bash
47# Download the checksum file (adjust version/arch)
48curl -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
49# Now verify (output should match the content of the .md5 file)
50if [ "$(md5 -q portainer-mcp-v0.2.0-darwin-arm64.tar.gz)" = "$(cat portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5)" ]; then echo "OK"; else echo "FAILED"; fi
51```
52 
53(For Linux, you can use `md5sum -c <checksum_file_name>.md5`)
54If the verification command outputs "OK", the file is intact.
55 
56**Extract the archive:**
57 
58```bash
59# Adjust the filename based on the downloaded version/OS/architecture
60tar -xzf portainer-mcp-v0.2.0-darwin-arm64.tar.gz
61```
62 
63This will extract the `portainer-mcp` executable.
64 
65**Move the executable:**
66Move the executable to a location in your `$PATH` (e.g., `/usr/local/bin`) or note its location for the configuration step below.
67 
68# Usage
69 
70With Claude Desktop, configure it like so:
71 
72```
73{
74    "mcpServers": {
75        "portainer": {
76            "command": "/path/to/portainer-mcp",
77            "args": [
78                "-server",
79                "[IP]:[PORT]",
80                "-token",
81                "[TOKEN]",
82                "-tools",
83                "/tmp/tools.yaml"
84            ]
85        }
86    }
87}
88```
89 
90Replace `[IP]`, `[PORT]` and `[TOKEN]` with the IP, port and API access token associated with your Portainer instance.
91 
92> [!NOTE]
93> By default, the tool looks for "tools.yaml" in the same directory as the binary. If the file does not exist, it will be created there with the default tool definitions. You may need to modify this path as described above, particularly when using AI assistants like Claude that have restricted write permissions to the working directory.
94 
95## Disable Version Check
96 
97By default, the application validates that your Portainer server version matches the supported version and will fail to start if there's a mismatch. If you have a Portainer server version that doesn't have a corresponding Portainer MCP version available, you can disable this version check to attempt connection anyway.
98 
99To disable the version check, add the `-disable-version-check` flag to your command arguments:
100 
101```
102{
103    "mcpServers": {
104        "portainer": {
105            "command": "/path/to/portainer-mcp",
106            "args": [
107                "-server",
108                "[IP]:[PORT]",
109                "-token",
110                "[TOKEN]",
111                "-disable-version-check"
112            ]
113        }
114    }
115}
116```
117 
118> [!WARNING]
119> Disabling the version check may result in unexpected behavior or API incompatibilities if your Portainer server version differs significantly from the supported version. The tool may work partially or not at all with unsupported versions.
120 
121When using this flag:
122- The application will skip Portainer server version validation at startup
123- Some features may not work correctly due to API differences between versions
124- Newer Portainer versions may have API changes that cause errors
125- Older Portainer versions may be missing APIs that the tool expects
126 
127This flag is useful when:
128- You're running a newer Portainer version that doesn't have MCP support yet
129- You're running an older Portainer version and want to try the tool anyway
130 
131## Tool Customization
132 
133By default, the tool definitions are embedded in the binary. The application will create a tools file at the default location if one doesn't already exist.
134 
135You can customize the tool definitions by specifying a custom tools file path using the `-tools` flag:
136 
137```
138{
139    "mcpServers": {
140        "portainer": {
141            "command": "/path/to/portainer-mcp",
142            "args": [
143                "-server",
144                "[IP]:[PORT]",
145                "-token",
146                "[TOKEN]",
147                "-tools",
148                "/path/to/custom/tools.yaml"
149            ]
150        }
151    }
152}
153```
154 
155The default tools file is available for reference at `internal/tooldef/tools.yaml` in the source code. You can modify the descriptions of the tools and their parameters to alter how AI models interpret and decide to use them. You can even decide to remove some tools if you don't wish to use them.
156 
157> [!WARNING]
158> Do not change the tool names or parameter definitions (other than descriptions), as this will prevent the tools from being properly registered and functioning correctly.
159 
160## Read-Only Mode
161 
162For security-conscious users, the application can be run in read-only mode. This mode ensures that only read operations are available, completely preventing any modifications to your Portainer resources.
163 
164To enable read-only mode, add the `-read-only` flag to your command arguments:
165 
166```
167{
168    "mcpServers": {
169        "portainer": {
170            "command": "/path/to/portainer-mcp",
171            "args": [
172                "-server",
173                "[IP]:[PORT]",
174                "-token",
175                "[TOKEN]",
176                "-read-only"
177            ]
178        }
179    }
180}
181```
182 
183When using read-only mode:
184- Only read tools (list, get) will be available to the AI model
185- All write tools (create, update, delete) are not loaded
186- The Docker proxy requests tool is not loaded
187- The Kubernetes proxy requests tool is not loaded
188 
189# Portainer Version Support
190 
191This tool is pinned to support a specific version of Portainer. The application will validate the Portainer server version at startup and fail if it doesn't match the required version.
192 
193| Portainer MCP Version  | Supported Portainer Version |
194|--------------|----------------------------|
195| 0.1.0 | 2.28.1 |
196| 0.2.0 | 2.28.1 |
197| 0.3.0 | 2.28.1 |
198| 0.4.0 | 2.29.2 |
199| 0.4.1 | 2.29.2 |
200| 0.5.0 | 2.30.0 |
201| 0.6.0 | 2.31.2 |
202 
203> [!NOTE]
204> If you need to connect to an unsupported Portainer version, you can use the `-disable-version-check` flag to bypass version validation. See the [Disable Version Check](#disable-version-check) section for more details and important warnings about using this feature.
205 
206# Supported Capabilities
207 
208The following table lists the currently (latest version) supported operations through MCP tools:
209 
210| Resource | Operation | Description | Supported In Version |
211|----------|-----------|-------------|----------------------|
212| **Environments** | | | |
213| | ListEnvironments | List all available environments | 0.1.0 |
214| | UpdateEnvironmentTags | Update tags associated with an environment | 0.1.0 |
215| | UpdateEnvironmentUserAccesses | Update user access policies for an environment | 0.1.0 |
216| | UpdateEnvironmentTeamAccesses | Update team access policies for an environment | 0.1.0 |
217| **Environment Groups (Edge Groups)** | | | |
218| | ListEnvironmentGroups | List all available environment groups | 0.1.0 |
219| | CreateEnvironmentGroup | Create a new environment group | 0.1.0 |
220| | UpdateEnvironmentGroupName | Update the name of an environment group | 0.1.0 |
221| | UpdateEnvironmentGroupEnvironments | Update environments associated with a group | 0.1.0 |
222| | UpdateEnvironmentGroupTags | Update tags associated with a group | 0.1.0 |
223| **Access Groups (Endpoint Groups)** | | | |
224| | ListAccessGroups | List all available access groups | 0.1.0 |
225| | CreateAccessGroup | Create a new access group | 0.1.0 |
226| | UpdateAccessGroupName | Update the name of an access group | 0.1.0 |
227| | UpdateAccessGroupUserAccesses | Update user accesses for an access group | 0.1.0 |
228| | UpdateAccessGroupTeamAccesses | Update team accesses for an access group | 0.1.0 |
229| | AddEnvironmentToAccessGroup | Add an environment to an access group | 0.1.0 |
230| | RemoveEnvironmentFromAccessGroup | Remove an environment from an access group | 0.1.0 |
231| **Stacks (Edge Stacks)** | | | |
232| | ListStacks | List all available stacks | 0.1.0 |
233| | GetStackFile | Get the compose file for a specific stack | 0.1.0 |
234| | CreateStack | Create a new Docker stack | 0.1.0 |
235| | UpdateStack | Update an existing Docker stack | 0.1.0 |
236| **Tags** | | | |
237| | ListEnvironmentTags | List all available environment tags | 0.1.0 |
238| | CreateEnvironmentTag | Create a new environment tag | 0.1.0 |
239| **Teams** | | | |
240| | ListTeams | List all available teams | 0.1.0 |
241| | CreateTeam | Create a new team | 0.1.0 |
242| | UpdateTeamName | Update the name of a team | 0.1.0 |
243| | UpdateTeamMembers | Update the members of a team | 0.1.0 |
244| **Users** | | | |
245| | ListUsers | List all available users | 0.1.0 |
246| | UpdateUser | Update an existing user | 0.1.0 |
247| | GetSettings | Get the settings of the Portainer instance | 0.1.0 |
248| **Docker** | | | |
249| | DockerProxy | Proxy ANY Docker API requests | 0.2.0 |
250| **Kubernetes** | | | |
251| | KubernetesProxy | Proxy ANY Kubernetes API requests | 0.3.0 |
252| | getKubernetesResourceStripped | Proxy GET Kubernetes API requests and automatically strip verbose metadata fields | 0.6.0 |
253 
254# Development
255 
256## Code Statistics
257 
258The repository includes a helper script `cloc.sh` to calculate lines of code and other metrics for the Go source files using the `cloc` tool. You might need to install `cloc` first (e.g., `sudo apt install cloc` or `brew install cloc`).
259 
260Run the script from the repository root to see the default summary output:
261 
262```bash
263./cloc.sh
264```
265 
266Refer to the comment header within the `cloc.sh` script for details on available flags to retrieve specific metrics.
267 
268## Token Counting
269 
270To get an estimate of how many tokens your current tool definitions consume in prompts, you can use the provided Go program and shell script to query the Anthropic API's token counting endpoint.
271 
272**1. Generate the Tools JSON:**
273 
274First, use the `token-count` Go program to convert your YAML tool definitions into the JSON format required by the Anthropic API. Run this from the repository root:
275 
276```bash
277# Replace internal/tooldef/tools.yaml with your YAML file if different
278# Replace .tmp/tools.json with your desired output path
279go run ./cmd/token-count -input internal/tooldef/tools.yaml -output .tmp/tools.json
280```
281 
282This command reads the tool definitions from the specified input YAML file and writes a JSON array of tools (containing `name`, `description`, and `input_schema`) to the specified output file.
283 
284**2. Query the Anthropic API:**
285 
286Next, use the `token.sh` script to send these tool definitions along with a sample message to the Anthropic API. You will need an Anthropic API key for this step.
287 
288```bash
289# Ensure you have jq installed
290# Replace sk-ant-xxxxxxxx with your actual Anthropic API key
291# Replace .tmp/tools.json with the path to the file generated in step 1
292./token.sh -k sk-ant-xxxxxxxx -i .tmp/tools.json
293```
294 
295The script will output the JSON response from the Anthropic API, which includes the estimated token count for the provided tools and sample message under the `usage.input_tokens` field.
296 
297This process helps in understanding the token cost associated with the toolset provided to the language model.
298