Portainer MCP Docker包装器
使用HTTP/SSE上的模型上下文协议（MCP）从Claude Code启用对Portainer实例的远程访问。
概述
该项目围绕以下内容创建了一个基于Docker的HTTP/SSE包装器 Portainer MCP服务器，允许在Windows计算机上运行的Claude Code远程控制在不同主机上运行的Portainer实例。
问题
官方Portainer MCP服务器使用 stdio传输 （stdin/stdout），它仅适用于本地子流程执行。这意味着只有当两者在同一台机器上运行时，Claude Code才能连接到Portainer。
解决方案
此包装提供 HTTP/SSE传输桥 即：
- 在Docker主机上作为Docker容器运行
- 通过HTTP/SSE公开Portainer MCP服务器
- 允许在Windows上从Claude Code进行安全的远程访问
- 与官方Portainer MCP保持完全兼容
建筑
Windows Machine (Claude Code)
-> HTTP/SSE Request (with Bearer token)
Docker Host (Wrapper Container)
-> Stdio Bridge
Portainer MCP Binary (Subprocess)
-> HTTP API
Portainer Instance主要特点
- 两层安全：包装器和Portainer的单独身份验证
- Docker原生：使用Docker Compose进行简单部署
- 占地面积最小：约20-30MB基于Alpine的图像
- 自动更新：在新的Portainer MCP版本发布时易于更新
- 健康检查：内置监测和健康端点
- 生产准备就绪：通过Caddy反向代理支持TLS
快速开始
先决条件
在开始之前，请确保您已经：
- 已安装Docker和Docker Compose
- 正在运行Portainer实例（v2.31.2+）
- Portainer API令牌
- Go 1.23+（用于开发）
完成检查表: 第1阶段-先决条件.md
安装
# 1. Clone the repository
git clone
cd portainer-mcp-docker-wrapper
# 2. Configure environment
cp .env.example .env
# Edit .env with your settings
# 3. Generate secure MCP access token
openssl rand -base64 32
# 4. Build and start
docker-compose up -d
# 5. Verify health
curl http://localhost:8081/health配置Claude代码
使用Claude Code CLI添加MCP服务器：
claude mcp add --transport http portainer http://:8081 --scope user然后在中手动添加Bearer令牌身份验证标头 C:\Users\\.claude.json:
{
"mcpServers": {
"portainer": {
"type": "http",
"url": "http://:8081",
"headers": {
"Authorization": "Bearer "
}
}
}
}备注：替换 ` 使用您的Docker主机IP（例如。， 192.168.0.242)以及 使用您的MCP_ACCESS_TOKEN .env` 文件。
文档
完整的文件
涵盖项目各个方面的综合文件。
入门指南
技术细节
快速链接
配置
环境变量
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
PORTAINER_URL | 是 | - | 门户实例URL（例如。， http://portainer:9000) |
PORTAINER_API_TOKEN | 是 | - | Portainer API令牌（以 ptr_) |
MCP_ACCESS_TOKEN | 是 | - | 用于向包装器进行身份验证的令牌（最少32个字符） |
MCP_PORT | 没有 | 8081 | 暴露HTTP端点的端口 |
MCP_TOOLS_FILE | 否 | - | 可选自定义工具配置 |
DISABLE_VERSION_CHECK | 没有 | false | 跳过Portainer版本兼容性检查 |
READ_ONLY_MODE | 没有 | false | 启用只读模式以确保安全 |
看 .env.示例 一个完整的模板。
安全
该项目实现了 双令牌安全模型:
- MCP访问令牌：对包装器的HTTP请求进行身份验证
- Portainer API代币：向Portainer验证包装器
安全最佳实践
- 生成强随机令牌：
openssl rand -base64 32 - 在生产环境中使用HTTPS（通过Caddy反向代理）
- 将令牌存储在环境变量中，而不是代码中
- 将Docker secrets用于生产部署
- 以非root用户身份运行容器（内置）
- 启用防火墙规则以限制访问
- 定期旋转令牌
看 安全架构 了解详情。
项目结构
portainer-mcp-docker-wrapper/
├── cmd/
│ └── wrapper/ # Main application
│ └── main.go
├── internal/
│ ├── auth/ # Authentication middleware
│ ├── bridge/ # MCP stdio bridge
│ └── config/ # Configuration management
├── docs/ # Comprehensive documentation
│ ├── 00-prerequisites-phase1.md
│ ├── 01-project-brief.md
│ ├── 02-implementation-plan.md
│ ├── 03-technical-architecture.md
│ ├── 04-code-examples.md
│ ├── 05-best-practices.md
│ └── README.md
├── Dockerfile # Multi-stage build
├── docker-compose.yml # Deployment configuration
├── .env.example # Configuration template
└── README.md # This file发展
从源头构建
# Initialize Go module
go mod init portainer-mcp-wrapper
go mod tidy
# Build wrapper
go build -o bin/wrapper ./cmd/wrapper
# Build Docker image
docker build -t portainer-mcp-wrapper:latest .测试
# Test health endpoint
curl http://localhost:8081/health
# Test with authentication
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8081/health
# View logs
docker-compose logs -f portainer-mcp实施阶段
该项目遵循7个阶段的实施计划：
| 阶段 | 描述 | 持续时间 |
|---|---|---|
| 第一阶段 | 建筑与设计 | 2-4小时 |
| 第2阶段 | 开发（Go包装器、Docker） | 8-12小时 |
| 第三期 | 客户端配置 | 1-2小时 |
| 阶段4 | 安全强化 | 2-4小时 |
| 阶段5 | 测试与验证 | 3-5小时 |
| 第6阶段 | 文档 | 2-3小时 |
| 第7阶段 | 部署和维护 | 1-2小时 |
| 总计 | 预计项目时间 | 19-32小时 |
看 实施计划 详细分类。
演出
- 延迟：每次操作30-160ms（可用于交互式使用）
- 记忆：每个容器约50-75MB
- 开销：包装层增加1-2ms
- 并发：支持多个并发的Claude Code会话
看 绩效预期 了解详情。
生产部署
对于使用HTTPS的生产部署，请使用Caddy反向代理：
# Start with HTTPS support
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d看 生产部署 有关配置详细信息。
故障排除
常见问题
容器无法启动
- 检查中的环境变量
.env - 验证门户URL是否可访问
- 确保API令牌有效
身份验证失败
- 验证
MCP_ACCESS_TOKEN匹配客户端配置 - 检查请求中的承载令牌格式
连接超时
- 验证网络连接
- 检查Docker主机上的防火墙规则（例如。，
sudo ufw allow 8081/tcp) - 确保端口8081未被阻塞
看 常见问题 更多解决方案。
外部资源
- MCP Go SDK: https://github.com/modelcontextprotocol/go-sdk
- 入口MCP: https://github.com/portainer/portainer-mcp
- MCP规范: https://modelcontextprotocol.io/
- Portainer API文档: https://docs.portainer.io/api/
贡献
欢迎投稿！拜托：
许可证
该项目的许可证与Portainer MCP项目相同。
致谢
- 建立在 入口MCP
- 用途 MCP Go SDK
- 设计用于 克劳德代码
______________________________________________________________________
准备好开始了吗？ 先决条件清单
需要帮助？ 完整的文件