AI导哈

Portainer Docker管理服务器

一个通过Portainer API让AI助手管理Docker容器的MCP服务器。

  • by caffeineflo
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 caffeineflo/portainer-mcp

使用说明

Portainer MCP服务器

MCP（模型上下文协议）服务器，使Claude等人工智能助手能够通过Portainer的API管理Docker容器。

公平警告： 这个项目已经彻底 vibe编码那是什么意思？这意味着我构建这个是为了个人使用和实验，主要是在共鸣和人工智能辅助开发的指导下。使用风险自负。请随时提交问题，但要知道他们会 氛围固定 也。没有保证，没有SLA，只有共鸣。

这是什么？

此MCP服务器充当AI模型和Portainer实例之间的桥梁。连接后，您的AI助手可以：

  • 列出并检查您的Docker环境、容器、堆栈、映像、卷和网络
  • 查看容器日志
  • 执行启动、停止和移除容器等操作
  • 部署新的Docker Compose堆栈
  • 管理Docker资源（镜像、卷、网络）

默认情况下，所有写入操作都是禁用的，必须显式启用。

快速开始

Docker（推荐）

# Pull and run
docker run --rm \
  -e PORTAINER_URL=https://portainer.example.com \
  -e PORTAINER_API_KEY=ptr_your_key_here \
  ghcr.io/caffeineflo/portainer-mcp:latest

Node.js

# Install dependencies
pnpm install

# Build
pnpm build

# Run
PORTAINER_URL=https://portainer.example.com \
PORTAINER_API_KEY=ptr_your_key_here \
node dist/index.js

配置

变量 必填 默认 描述
PORTAINER_URL 是 - 您的Portainer实例URL
PORTAINER_API_KEY 是 - Portainer API访问令牌
PORTAINER_WRITE_ENABLED 没有 false 设置为 true 启用写入操作

获取Portainer API密钥

  1. 登录Portainer
  2. 首选 我的账户 → 访问令牌
  3. 点击 添加访问令牌
  4. 给它一个描述性的名称，并复制生成的令牌

Claude桌面集成

添加到您的Claude Desktop配置中：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %APPDATA%\Claude\claude_desktop_config.json

使用Docker

{
  "mcpServers": {
    "portainer": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PORTAINER_URL=https://portainer.example.com",
        "-e", "PORTAINER_API_KEY=ptr_your_api_key_here",
        "-e", "PORTAINER_WRITE_ENABLED=true",
        "ghcr.io/caffeineflo/portainer-mcp:latest"
      ]
    }
  }
}

使用Node.js

{
  "mcpServers": {
    "portainer": {
      "command": "node",
      "args": ["/path/to/portainer-mcp/dist/index.js"],
      "env": {
        "PORTAINER_URL": "https://portainer.example.com",
        "PORTAINER_API_KEY": "ptr_your_api_key_here",
        "PORTAINER_WRITE_ENABLED": "true"
      }
    }
  }
}

可用工具

只读（始终可用）

工具 说明
list_environments 列出所有Portainer环境（Docker端点）
list_containers 列出环境中的容器（可选地包括已停止的容器）
inspect_container 获取容器的详细信息
container_logs 获取容器日志（默认100行，最多10000行）
list_stacks 列出所有堆栈（可选按环境筛选）
inspect_stack 获取堆栈详细信息，包括编写文件内容
list_images 列出环境中的Docker镜像
list_volumes 列出环境中的Docker卷
list_networks 列出环境中的Docker网络

写入操作（必需 PORTAINER_WRITE_ENABLED=true)

工具 说明
container_action 启动、停止、重启、终止或移除容器
stack_action 启动、停止或删除堆栈
create_stack 创建新的Docker Compose堆栈
manage_image 拉取或删除Docker镜像
manage_volume 创建或删除Docker卷
manage_network 创建或删除Docker网络（具有可选的自定义子网）

示例工作流

检查正在运行的内容

You: What containers are running in my environment?

Claude: Let me check...
→ list_environments
→ list_containers(environment_id=1)

You have 5 containers running:
- nginx (Up 2 days)
- postgres (Up 2 days)
- redis (Up 5 hours)
...

查看有问题容器的日志

You: Show me the last 50 lines of logs from the api container

Claude:
→ container_logs(environment_id=1, container_id="api", tail=50)

部署新堆栈

You: Deploy an nginx container as a stack called "webserver"

Claude:
→ create_stack(
    environment_id=1,
    name="webserver",
    compose_content="services:\n  web:\n    image: nginx:latest\n    ports:\n      - '8080:80'"
  )

发展

# Install dependencies
pnpm install

# Build TypeScript
pnpm build

# Watch mode (rebuild on changes)
pnpm dev

# Run tests
pnpm test

# Bundle for distribution
pnpm bundle

# Build Docker image
docker build -t portainer-mcp .

项目结构

src/
├── index.ts           # MCP server entry point
├── client.ts          # Portainer API client
├── types.ts           # TypeScript type definitions
├── schemas.ts         # Zod validation schemas
└── tools/
    ├── index.ts       # Tool registry and dispatcher
    ├── definitions.ts # MCP tool JSON Schema definitions
    ├── utils.ts       # Response formatting utilities
    ├── environments.ts
    ├── containers.ts
    ├── stacks.ts
    ├── images.ts
    ├── volumes.ts
    └── networks.ts

技术栈

  • TypeScript -全程类型安全
  • @模型上下文协议/sdk -MCP协议实现
  • 萨德 -工具参数的运行时验证
  • Node.js 18+ -运行时间要求
  • 码头工人 -优化的多阶段构建（约148MB图像）

许可证

麻省理工学院

相关 MCP