Burly MCP

MCP运维云端

提供方 Wolfeitz

运维云端 stdio · 本地进程 Token 社区 / 第三方 Claude
查看接入方式

Burly MCP Server 是一个安全、策略驱动的模型上下文协议服务器,使AI助手能够通过标准化接口安全执行系统操作。

一句话选型结论

按资料字段整理

Burly MCP 属于运维云端类 MCP 服务器,stdio · 本地进程,Token,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 4 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量4暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

AI系统集成Python本地部署安全协议系统操作容器化部署策略驱动

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
docker run --rm -p 9400:9400 ghcr.io/wolfeitz/burlymcp:main

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Docker,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 4 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 4 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Burly MCP当前 4 stdio · 本地进程 本地部署 有 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方Wolfeitz上游标注的维护方 Wolfeitz
分类运维云端本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Docker本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

31.2 KB
来自项目仓库与上游目录的原文,未做删改

Burly MCP服务器

一个安全的、策略驱动的模型上下文协议(MCP)服务器,使AI助手能够通过标准化的接口安全地执行系统操作。

什么是MCP,你为什么要关心?

这 模型上下文协议(MCP) 是人工智能助手与外部工具和服务交互的标准化方式。将其视为人工智能系统和基础设施之间的安全桥梁。

MCP解决的问题

传统的人工智能助手仅限于文本生成,无法直接与您的系统交互。当你要求人工智能“检查我的Docker容器”或“发布我的博客文章”时,它只能给你手动运行的命令。

MCP解决方案

MCP使AI助手能够:

  • ✅ 安全地执行真实的系统操作
  • ✅ 遵循严格的安全政策
  • ✅ 提供即时、可操作的结果
  • ✅ 维护全面的审计跟踪

为什么“埋葬”MCP?

这种实现是“健壮的”,因为它是以安全性和健壮性为主要关注点构建的:

  • 策略驱动:只允许白名单操作
  • 容器化:以最小权限独立运行
  • 已审核:记录每项操作以确保合规性
  • 确认:危险操作需要明确批准

运行时容器接口

BurlyMCP作为一个独立的服务容器分发,它公开HTTP端点以与下游系统集成。容器提供了一个稳定的API契约,该契约在内部实现更改中保持一致。

集装箱合同

官方界面:

  • 端口:9400(HTTP)
  • 健康检查: GET /health (别名: GET /v1/health)-返回服务状态和功能
  • MCP端点: POST /mcp (别名: POST /v1/mcp)-通过HTTP接受MCP协议请求
  • 过程:以PID 1运行,在SIGTERM上优雅关闭(≤10秒)

已发布图片:

  • ghcr.io/wolfeitz/burlymcp:main -主分支最新稳定构建
  • ghcr.io/wolfeitz/burlymcp:- -可追溯性的特定提交构建

快速入门(容器)```bash

Start the container (no privileges required)

docker run --rm -p 9400:9400 ghcr.io/wolfeitz/burlymcp:main

Test health endpoint

curl http://127.0.0.1:9400/health

Test MCP functionality via HTTP bridge

curl -X POST http://127.0.0.1:9400/mcp \
-H 'content-type: application/json' \
-d '{"id":"1","method":"list_tools","params":{}}'


容器成功启动,没有任何外部依赖关系、配置文件或提升的权限。

## 快速入门(Docker Compose)```bash
# Using the example compose file
docker compose -f examples/compose/docker-compose.yaml up -d

# List tools
curl -sS -H 'Content-Type: application/json' \
-d '{"id":"1","method":"list_tools","params":{}}' \
http://localhost:9400/mcp | jq

# Call a tool
curl -sS -H 'Content-Type: application/json' \
-d '{"id":"2","method":"call_tool","params":{"name":"disk_space","arguments":{}}}' \
http://localhost:9400/mcp | jq
  • 基于目录的配置示例:请参阅 examples/config/.
  • 撰写装载示例的文章:请参阅 examples/compose/docker-compose.yaml.
  • REST客户端/curl示例:请参阅 examples/requests/.

部署选项

最小模式(建议用于测试):```bash
docker run --rm -p 9400:9400 ghcr.io/wolfeitz/burlymcp:main


- 无需提升权限
- 可用的基本系统工具(disk_space等)
- 如果套接字未安装,Docker工具会优雅地降级

**特权模式(Docker操作):**```bash
# Get your Docker group GID
DOCKER_GID=$(getent group docker | cut -d: -f3)

# Run with Docker socket access
docker run --rm -p 9400:9400 \
--group-add $DOCKER_GID \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
ghcr.io/wolfeitz/burlymcp:main
  • 启用Docker检查工具(Docker_ps)
  • 安全警告:挂载Docker套接字授予root对主机的等效访问权限

生产模式(持久数据):```bash
docker run -d --name burlymcp \
-p 9400:9400 \
-v ./logs:/var/log/agentops \
-v ./blog/stage:/app/data/blog/stage:ro \
-v ./blog/publish:/app/data/blog/publish:rw \
-e GOTIFY_URL=https:// \
-e GOTIFY_TOKEN= \
ghcr.io/wolfeitz/burlymcp:main


### 环境变量

**核心配置:**

- `LOG_LEVEL` -日志详细程度(调试、信息、警告、错误)\[默认值:信息\]
- `AUDIT_LOG_PATH` -审核日志文件位置\[默认值:/var/log/agentops/Audit.json\]
- `POLICY_FILE` -策略配置文件\[默认值:/config/Policy/tools.yaml\]

**博客管理:**

- `BLOG_STAGE_ROOT` -博客内容的暂存目录\[默认:/app/data/blog/stage\]
- `BLOG_PUBLISH_ROOT` -博客内容的发布目录\[默认:/app/data/blog/publish\]

**通知(可选):**

- `GOTIFY_URL` -用于通知的Gotify服务器URL\[默认:禁用\]
- `GOTIFY_TOKEN` -Gotify应用程序令牌\[默认:禁用\]

**安全:**

- `STRICT_SECURITY_MODE` -启用严格安全验证\[默认值:true\]
- `RATE_LIMIT_DISABLED` -禁用API速率限制以供实验室使用\[默认值:false\]

**Docker集成:**

- `DOCKER_SOCKET` -Docker套接字路径\[默认:/var/run/Docker.sock\]
- `DOCKER_TIMEOUT` -Docker操作超时(秒)\[默认值:30\]

**容器运行时:**

- `PORT` -HTTP服务器端口\[默认值:9400\]
- `HOST` -HTTP服务器绑定地址\[默认值:0.0.0.0\]
- `SERVER_NAME` -服务器标识符\[默认值:burlymcp\]
- `SERVER_VERSION` -版本字符串\[默认值:1.0.0\]

### 安全注意事项

**集装箱安全:**

- 以非root用户(mcp:1000)身份运行,具有最低权限
- 使用debian:trixie苗条的基础图像来保证安全性和尺寸
- 不包括Docker守护进程-只有可选的客户端功能
- 环境变量净化可防止秘密泄露到子流程

**API安全:**

- 默认情况下启用速率限制(每个IP每分钟60个请求)
- 请求大小限制可防止资源耗尽(最大10KB)
- 对所有端点进行输入净化和验证
- 结构化错误响应可防止信息泄露

**可选提升特权:**

- Docker套接字挂载是操作员的选择,从不需要
- 博客目录挂载需要适当的文件权限
- 通知令牌应通过环境变量提供,而不是嵌入

### 关闭行为

容器优雅地处理关机:

- 对SIGTERM的响应是优雅关机
- 在10秒内完成飞行中的请求
- 刷新审核日志并关闭文件句柄
- 带有适当状态代码的出口

**PID 1期望值:**

- HTTP桥(uvicorn)在容器内以PID 1运行
- 处理信号转发和僵尸进程收割
- 在收到关机信号之前保持服务可用性

## 快速开始

### 先决条件

**系统要求:**

- Docker(用于容器部署)
- Linux主机(任何支持Docker的发行版)
- 集装箱化的基本理解

**可选依赖关系:**

- Docker守护进程(用于Docker检查工具)
- Gotify服务器(用于通知)
- 持久存储(用于审计日志和博客内容)

### 1.基本容器测试```bash
# Pull and test the container
docker run --rm -p 9400:9400 ghcr.io/wolfeitz/burlymcp:main

# In another terminal, verify it's working
curl http://localhost:9400/health

2.与Open WebUI集成

看 docs/open-webui.md 获取详细的集成说明。

3.Docker编写示例

有关docker compose部署示例,请参阅 示例/组成/ 目录。这些只是参考配置-官方部署方法是发布的容器映像。

MCP协议集成

Burly MCP支持模型上下文协议(MCP),用于与AI助手和其他MCP客户端集成。服务器提供 两条整合路径:

1.本地MCP协议(推荐)

服务器通过stdin/stdout使用JSON-RPC 2.0实现了完整的MCP规范:```bash

Direct MCP integration (development)

python -m burly_mcp.server.main

Docker-based MCP integration (production)

docker exec -i burlymcp python3 -m burly_mcp.server.main

Example MCP request

echo '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' | \
docker exec -i burlymcp python3 -m burly_mcp.server.main


**支持的MCP方法:**

- `initialize` -服务器握手和能力协商
- `tools/list` -列出具有JSON模式的可用工具
- `tools/call` -使用结构化参数执行工具
- `notifications/cancelled` -处理通知取消
- `notifications/initialized` -客户端初始化确认

**MCP客户端配置(Kiro/Claude桌面):**```json
{
"mcpServers": {
"burly-mcp": {
"command": "docker",
"args": ["exec", "-i", "burlymcp", "python3", "-m", "burly_mcp.server.main"],
"env": {},
"disabled": false,
"autoApprove": ["disk_space", "docker_ps"]
}
}
}

开发MCP配置:```json
{
"mcpServers": {
"burly-mcp": {
"command": "python3",
"args": ["-m", "burly_mcp.server.main"],
"env": {
"POLICY_FILE": "config/policy/tools.yaml",
"PYTHONPATH": "src"
},
"cwd": "/path/to/BurlyMCP"
}
}
}


### 2.HTTP网桥(传统兼容性)

对于需要HTTP API兼容性或具有集成挑战的系统,我们提供了一个在MCP协议和HTTP API之间转换的HTTP桥:```bash
# Using the HTTP bridge
python mcp_http_bridge.py

该网桥连接到HTTP服务器(端口9400),并提供完全的MCP协议兼容性。看 docs/http-bridge.md 详细文档。

何时使用大桥:

  • 使用HTTP API的旧系统
  • 无需更改服务器即可快速集成MCP
  • 需要HTTP和MCP访问的混合部署
  • 迁移前测试MCP集成

桥接配置:```json
{
"mcpServers": {
"burly-mcp": {
"command": "python3",
"args": ["mcp_http_bridge.py"],
"env": {
"BURLYMCP_BASE_URL": "http://localhost:9400"
}
}
}
}


## 可用工具

Burly MCP提供以下系统操作工具:

### 📦 Docker操作

- **`docker_ps`**:列出正在运行的容器及其状态信息
- 对Docker守护进程的安全只读访问

### 💾 系统监控

- **`disk_space`**:检查跨已装载卷的文件系统使用情况
- 帮助监控存储容量和使用模式

### 📝 博客管理

- **`blog_stage_markdown`**:使用YAML front matter验证博客文章
- **`blog_publish_static`**:发布经过验证的内容(需要确认)
- 具有路径遍历保护的安全文件操作

### 🔔 通知

- **`gotify_ping`**:通过Gotify发送测试通知
- 可选集成操作警报

## 安全模型

Burly MCP实施深度防御安全:

### 🛡️ 集装箱安全

- 以非root用户身份运行(`agentops:1000`)
- 具有最小可写区域的只读文件系统
- 没有暴露的网络端口(仅限stdin/stdout)
- 资源限制防止资源耗尽

### 📋 政策执行

- 所有工具必须明确列入白名单 `policy/tools.yaml`
- 所有工具参数的JSON模式验证
- 文件操作的路径遍历保护
- 超时强制防止挂起操作

### 🔍 审计和监测

- 以JSON Lines格式记录的每个操作
- 参数哈希在启用审计的同时保护隐私
- 用于实时监控的可选Gotify通知
- 全面的执行指标和错误跟踪

### ⚠️ 确认工作流程

- 突变操作需要明确确认
- 两步过程防止意外破坏行为
- 明确指出将要修改的内容

## 配置和部署

### 默认内部路径

容器包含这些默认路径,无需外部挂载即可工作:

**配置文件:**

- `/config/policy/tools.yaml` -默认策略文件(嵌入在图像中)
- `/app/BurlyMCP/` -完整的BurlyMCP源代码树

**数据目录:**

- `/var/log/agentops/audit.jsonl` -审核日志文件
- `/var/log/agentops/` -日志目录
- `/app/data/blog/stage/` -博客暂存目录
- `/app/data/blog/publish/` -博客发布目录

**运行时环境:**

- `/opt/venv/` -Python虚拟环境
- `/app/` -应用程序根目录
- 用户: `mcp` (UID 1000,GID 1000)

### 环境变量覆盖

所有默认路径和设置都可以通过环境变量覆盖:

**核心配置:**```bash
# Logging and Audit
LOG_LEVEL=INFO                                    # DEBUG, INFO, WARNING, ERROR
AUDIT_LOG_PATH=/var/log/agentops/audit.jsonl     # Audit log file location
POLICY_FILE=/config/policy/tools.yaml # Policy configuration file

# Server Settings
PORT=9400                                         # HTTP server port
SERVER_NAME=burlymcp                             # Server identifier
SERVER_VERSION=0.1.0                            # Version string
STRICT_SECURITY_MODE=true                        # Enable strict security validation

博客管理:```bash

Blog Content Directories

BLOG_STAGE_ROOT=/app/data/blog/stage # Staging directory (read-only)
BLOG_PUBLISH_ROOT=/app/data/blog/publish # Publication directory (read-write)

Blog Tool Settings

MAX_OUTPUT_SIZE=1048576 # Maximum tool output size (1MB)


**Docker集成:**```bash
# Docker Configuration
DOCKER_SOCKET=/var/run/docker.sock              # Docker socket path
DOCKER_TIMEOUT=30                                # Docker operation timeout (seconds)

通知(可选):```bash

Gotify Integration

GOTIFY_URL=https:// # Gotify server URL
GOTIFY_TOKEN= # Gotify app token
NOTIFICATIONS_ENABLED=false # Enable/disable notifications


**API安全:**```bash
# Rate Limiting and Security
RATE_LIMIT_DISABLED=false                        # Disable rate limiting for lab use
MAX_REQUEST_SIZE=10240                           # Maximum request body size (10KB)

用于数据持久化的卷装载

审核日志(建议用于生产):```bash
-v ./logs:/var/log/agentops


- 在容器重启过程中保持审计跟踪
- 支持日志分析和合规性报告
- 目录必须可由UID 1000写入

**博客内容管理:**```bash
-v ./blog/stage:/app/data/blog/stage:ro          # Staging content (read-only)
-v ./blog/publish:/app/data/blog/publish:rw      # Published content (read-write)
  • 启用blog_stage_markdown和blog_publish_static工具
  • 为了安全起见,暂存目录应该是只读的
  • 发布目录需要UID 1000的写访问权限

自定义策略文件:```bash
-v ./custom-policy.yaml:/config/policy/tools.yaml:ro


- 使用自定义工具配置覆盖默认策略
- 文件必须可由UID 1000读取
- 更改需要重新启动容器

### 部署场景

**场景1:开发/测试(最小)**```bash
docker run --rm -p 9400:9400 ghcr.io/wolfeitz/burlymcp:main
  • 无外部依赖关系
  • 仅限基本系统工具
  • 临时审计日志
  • 适用于API测试和开发

场景2:生产监控(持久日志)```bash
docker run -d --name burlymcp \
-p 9400:9400 \
-v ./logs:/var/log/agentops \
-e LOG_LEVEL=WARNING \
-e GOTIFY_URL=https:// \
-e GOTIFY_TOKEN= \
--restart unless-stopped \
ghcr.io/wolfeitz/burlymcp:main


- 持续审计日志记录
- 生产通知集成
- 故障时自动重启
- 减少日志冗长

**场景3:基础设施操作(Docker Access)**```bash
# Get Docker group GID
DOCKER_GID=$(getent group docker | cut -d: -f3)

docker run -d --name burlymcp-ops \
-p 9400:9400 \
--group-add $DOCKER_GID \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v ./logs:/var/log/agentops \
-e LOG_LEVEL=INFO \
--restart unless-stopped \
ghcr.io/wolfeitz/burlymcp:main
  • ⚠️ 安全警告:Docker套接字访问授予root等效主机访问权限
  • 启用docker_ps和集装箱检查工具
  • 应仅在受信任的网络上使用
  • 考虑防火墙规则以限制对端口9400的访问

场景4:内容管理(博客发布)```bash
docker run -d --name burlymcp-blog \
-p 9400:9400 \
-v ./blog/content:/app/data/blog/stage:ro \
-v ./blog/public:/app/data/blog/publish:rw \
-v ./logs:/var/log/agentops \
-e BLOG_STAGE_ROOT=/app/data/blog/stage \
-e BLOG_PUBLISH_ROOT=/app/data/blog/publish \
--restart unless-stopped \
ghcr.io/wolfeitz/burlymcp:main


- 启用博客内容管理工具
- 为安全起见,临时目录以只读方式装载
- 发布目录需要写访问权限
- 审计日志跟踪所有发布操作

**场景5:高安全性(气隙)**```bash
docker run -d --name burlymcp-secure \
-p 127.0.0.1:9400:9400 \
-v ./logs:/var/log/agentops \
-e RATE_LIMIT_DISABLED=false \
-e STRICT_SECURITY_MODE=true \
-e LOG_LEVEL=DEBUG \
--read-only \
--tmpfs /tmp:noexec,nosuid,size=100m \
--restart unless-stopped \
ghcr.io/wolfeitz/burlymcp:main
  • 仅绑定到本地主机(无外部访问)
  • 具有最小tmpfs的只读文件系统
  • 增强的安全日志记录
  • 实施利率限制
  • 无外部网络依赖关系

安全警告和最佳实践

Docker套接字安装:

  • ⚠️ 关键的:安装 /var/run/docker.sock 授予主机root等效访问权限
  • 仅在受信任的隔离网络上挂载Docker套接字
  • 考虑在Docker中使用Docker或无根Docker进行额外隔离
  • 监控所有Docker操作的审计日志

网络曝光:

  • 默认绑定(0.0.0.0:9400)将服务暴露给所有网络接口
  • 对于生产,考虑绑定到特定接口: -p 127.0.0.1:9400:9400
  • 使用带有身份验证的反向代理进行外部访问
  • 实施网络级访问控制(防火墙、VPN)

秘密管理:

  • 永远不要在容器映像或docker compose文件中嵌入机密
  • 对敏感数据使用环境变量或Docker机密
  • 定期旋转Gotify代币
  • 监控审核日志,防止未经授权的访问尝试

文件权限:

  • 确保装载的目录具有正确的所有权(UID 1000)
  • 尽可能使用只读装载(暂存目录、策略文件)
  • 定期检查持久卷上的文件权限
  • 考虑使用命名卷而不是绑定挂载,以获得更好的隔离

策略配置

容器包含一个可以自定义的默认策略文件:

默认策略位置: /config/policy/tools.yaml

自定义策略覆盖:```bash

Mount custom policy file

-v ./my-policy.yaml:/config/policy/tools.yaml:ro


**自定义策略示例:**```yaml
tools:
# System monitoring (safe, read-only)
disk_space:
description: "Check filesystem usage"
timeout_sec: 30
notify: ["failure"]
mutates: false
requires_confirm: false

# Docker operations (requires socket mount)
docker_ps:
description: "List Docker containers"
timeout_sec: 30
notify: ["failure", "success"]
mutates: false
requires_confirm: false

# Blog publishing (mutating operation)
blog_publish_static:
description: "Publish blog content"
timeout_sec: 60
notify: ["success", "failure"]
mutates: true
requires_confirm: true
args_schema:
type: "object"
properties:
source_file: {"type": "string"}
target_path: {"type": "string"}
required: ["source_file"]

# Notifications (optional feature)
gotify_ping:
description: "Send test notification"
timeout_sec: 10
notify: ["failure"]
mutates: false
requires_confirm: false

策略验证:

  • 策略文件在容器启动时进行验证
  • 无效的策略阻止容器启动
  • 检查容器日志中是否存在策略验证错误
  • 使用 docker logs 调试策略问题

发展

地方发展设置```bash

Install Python dependencies

pip install -e ".[dev]"

Run tests

pytest

Run with coverage

pytest --cov=burly_mcp

Format code

black src/ tests/
isort src/ tests/

Type checking

mypy src/


### 核心依赖关系

Burly MCP服务器需要以下Python包:

**运行时依赖关系:**

- `pydantic>=2.5.0` -数据验证和设置管理
- `pyyaml>=6.0.1` -策略配置的YAML解析
- `jsonschema>=4.20.0` -工具参数的JSON模式验证
- `requests>=2.31.0` -Gotify通知的HTTP客户端
- `docker>=7.0.0` -用于容器操作的Docker API客户端

**开发依赖性:**

- `pytest>=7.4.0` -测试框架
- `pytest-cov>=4.1.0` -测试覆盖率报告
- `pytest-asyncio>=0.21.0` -异步测试支持
- `black>=23.0.0` -代码格式
- `isort>=5.12.0` -导入排序
- `flake8>=6.0.0` -Linting
- `mypy>=1.7.0` -静态类型检查
- `pre-commit>=3.5.0` -Git挂钩提高代码质量

所有依赖项都会自动安装 `pip install -e ".[dev]"`

### 安全验证

在提交代码之前运行安全检查:```bash
# Check for secrets and credentials
gitleaks detect --source . --verbose

# Scan for vulnerabilities
trivy filesystem .

# Check Python dependencies (if using npm for tooling)
npm audit --production-only

# Validate Python syntax and imports
python -c "import burly_mcp.server.main; print('Syntax OK')"

这些安全检查有助于确保:

  • 没有秘密是意外泄露的
  • 依赖关系没有已知漏洞
  • 代码遵循安全最佳实践
  • 所有导入和语法均有效

添加新工具

  1. 在中定义工具 config/policy/tools.yaml
  2. 在中实现工具功能 src/burly_mcp/tools/registry.py
  3. 在中添加测试 tests/unit/test_tools.py
  4. 更新文档

看 docs/config.md 了解详细的配置选项。

建筑```

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ MCP Clients │ │ Burly MCP │ │ System Tools │
│ (Kiro, etc.) │◄──►│ Server │◄──►│ │
│ │ │ │ │ Docker, Files, │
│ │ │ Policy Engine │ │ Notifications │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌──────────────┐
│ Audit Logs │
│ (JSON Lines) │
└──────────────┘


### 集成路径

**原生MCP(推荐)**:

- 通过标准输入/标准输出直接JSON-RPC 2.0
- 完全符合MCP协议
- 最佳性能和兼容性

**HTTP网桥(传统)**:

- 将MCP协议转换为HTTP API调用
- 保持向后兼容性
- 适用于混合部署

看 docs/http-bridge.md 获取详细的桥梁文档。

## 替代方案:手动安装

如果你想在没有Docker的情况下运行:```bash
# Install Python dependencies
pip install -e .

# Create required directories
mkdir -p ./logs ./blog/stage ./blog/publish

# Set environment variables for local development
export POLICY_FILE=config/policy/tools.yaml
export AUDIT_LOG_PATH=./logs/audit.jsonl
export LOG_DIR=./logs
export BLOG_STAGE_ROOT=./blog/stage
export BLOG_PUBLISH_ROOT=./blog/publish
export NOTIFICATIONS_ENABLED=false

# Run the MCP server
python -m burly_mcp.server.main

注: 手动安装需要:

  • Python 3.12+
  • 日志和博客内容的本地目录
  • 为本地路径配置的环境变量
  • Docker守护进程正在运行(适用于Docker工具,可选)

文档

  • 📖 完整配置指南
  • 🔒 安全模型与威胁分析
  • 🚀 部署和运营
  • 🤖 打开WebUI集成
  • 📚 了解MCP协议

贡献

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 通过测试进行更改
  4. 运行测试套件(pytest)
  5. 提交您的更改(git commit -m 'Add amazing feature')
  6. 推到分支(git push origin feature/amazing-feature)
  7. 打开拉取请求

开发指南

  • 所有新工具都必须包括全面的测试
  • 必须记录安全影响
  • 遵循现有的代码样式(黑色+isort)
  • 更新面向用户的更改文档
  • 在提交PR之前运行安全验证:```bash

Required security checks

gitleaks detect --source .
trivy filesystem .
python -c "import burly_mcp.server.main; print('Syntax OK')"


## 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

## 故障弱化

BurlyMCP设计用于在可选功能不可用时正常工作:

### Docker工具降级

**当Docker套接字未被挂载时:**```json
{
"ok": false,
"summary": "Docker unavailable",
"error": "Docker socket not accessible in this container",
"data": {
"suggestion": "Mount /var/run/docker.sock and add docker group to enable Docker operations"
}
}

要启用Docker工具:```bash

Find your Docker group GID

getent group docker

Example output: docker:x::user1,user2

Use the numeric GID from the output

docker run -p 9400:9400 \
--group-add \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
ghcr.io/wolfeitz/burlymcp:main


### 通知系统降级

**当Gotify未配置时:**

- 通知工具返回成功,但日志“未配置”
- 无错误或服务中断
- 操作正常进行,无需通知

**要启用通知,请执行以下操作:**```bash
docker run -p 9400:9400 \
-e GOTIFY_URL=https:// \
-e GOTIFY_TOKEN= \
ghcr.io/wolfeitz/burlymcp:main

博客工具降级

当博客目录未被挂载时:

  • 博客工具返回结构化错误,并提供有用的建议
  • 未尝试任何文件系统操作
  • 服务保持稳定和响应迅速

要启用博客工具,请执行以下操作:```bash
docker run -p 9400:9400 \
-v :/app/data/blog/stage:ro \
-v :/app/data/blog/publish:rw \
ghcr.io/wolfeitz/burlymcp:main


## 故障排除

### 容器启动问题

**容器无法启动:**```bash
# Check container logs
docker logs

# Common issues:
# 1. Port 9400 already in use
docker run -p 9401:9400 ghcr.io/wolfeitz/burlymcp:main

# 2. Permission issues with mounted volumes
sudo chown -R 1000:1000

# 3. Invalid policy file
docker run --rm ghcr.io/wolfeitz/burlymcp:main python -c "
import yaml
with open('/config/policy/tools.yaml') as f:
print('Policy valid:', yaml.safe_load(f))
"

健康检查失败:```bash

Test health endpoint directly

curl -v http://localhost:9400/health

Expected response:

HTTP/1.1 200 OK

{"status":"ok","server_name":"burlymcp",...}

If connection refused:

1. Check if container is running: docker ps

2. Check port mapping: docker port

3. Check firewall rules


### Docker套接字访问问题

**Docker工具返回“不可用”错误:**

1. **验证Docker套接字是否存在:**```bash
ls -la /var/run/docker.sock
# Should show: srw-rw---- 1 root docker ... /var/run/docker.sock
  1. 查找Docker组GID:```bash
    getent group docker

Example output: docker:x::user1,user2

Use the numeric GID from the output in --group-add


1. **在容器中测试Docker访问:**```bash
docker run --rm -it \
--group-add  \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
ghcr.io/wolfeitz/burlymcp:main \
docker ps
  1. 常见的Docker套接字问题:```bash

Permission denied

sudo usermod -aG docker $USER
newgrp docker # or logout/login

Socket not found (Docker not running)

sudo systemctl start docker
sudo systemctl enable docker

SELinux issues (RHEL/CentOS)

sudo setsebool -P container_manage_cgroup on


### 网络和连接问题

**无法从主机访问容器:**```bash
# Check container is listening
docker exec  netstat -tlnp | grep 9400

# Check port mapping
docker port

# Test from inside container
docker exec  curl http://localhost:9400/health

# Test with different binding
docker run -p 127.0.0.1:9400:9400 ghcr.io/wolfeitz/burlymcp:main  # localhost only
docker run -p 0.0.0.0:9400:9400 ghcr.io/wolfeitz/burlymcp:main   # all interfaces

利率限制问题:```bash

Disable rate limiting for testing

docker run -p 9400:9400 \
-e RATE_LIMIT_DISABLED=true \
ghcr.io/wolfeitz/burlymcp:main

Check rate limit headers

curl -v -X POST http://localhost:9400/mcp \
-H 'content-type: application/json' \
-d '{"id":"1","method":"list_tools","params":{}}'


### 文件权限问题

**无法访问已安装的卷:**```bash
# Check ownership of mounted directories
ls -la

# Fix ownership (container runs as UID 1000)
sudo chown -R 1000:1000

# Test write access for blog publishing
docker run --rm \
-v :/app/data/blog/publish:rw \
ghcr.io/wolfeitz/burlymcp:main \
touch /app/data/blog/publish/test-write

审核日志权限错误:```bash

Create log directory with correct permissions

mkdir -p ./logs
sudo chown 1000:1000 ./logs
chmod 755 ./logs

Test log writing

docker run --rm \
-v ./logs:/var/log/agentops \
ghcr.io/wolfeitz/burlymcp:main \
touch /var/log/agentops/test.log


### 配置和策略问题

**策略文件无效:**```bash
# Validate policy syntax
python3 -c "
import yaml
try:
with open('your-policy.yaml') as f:
policy = yaml.safe_load(f)
print('Policy syntax valid')
print('Tools defined:', list(policy.get('tools', {}).keys()))
except Exception as e:
print('Policy error:', e)
"

# Test with minimal policy
cat > minimal-policy.yaml << EOF
tools:
disk_space:
description: "Check disk usage"
timeout_sec: 30
mutates: false
requires_confirm: false
EOF

docker run --rm -p 9400:9400 \
-v ./minimal-policy.yaml:/config/policy/tools.yaml:ro \
ghcr.io/wolfeitz/burlymcp:main

环境变量问题:```bash

Debug environment variables

docker run --rm \
-e LOG_LEVEL=DEBUG \
ghcr.io/wolfeitz/burlymcp:main \
env | grep -E "(GOTIFY|BLOG|DOCKER|LOG)"

Test configuration loading

docker run --rm \
-e LOG_LEVEL=DEBUG \
ghcr.io/wolfeitz/burlymcp:main \
python3 -c "
from burly_mcp.config import load_runtime_config
config = load_runtime_config()
print('Config loaded successfully')
print('Blog stage root:', config.blog_stage_root)
print('Notifications enabled:', config.notifications_enabled)
"


### 性能和资源问题

**容器使用了太多内存:**```bash
# Monitor resource usage
docker stats

# Set memory limits
docker run -p 9400:9400 \
--memory=512m \
--memory-swap=512m \
ghcr.io/wolfeitz/burlymcp:main

# Check for memory leaks in logs
docker logs  | grep -i "memory\|oom"

响应时间慢:```bash

Test response time

time curl http://localhost:9400/health

Check for blocking operations

docker exec ps aux

Enable debug logging

docker run -p 9400:9400 \
-e LOG_LEVEL=DEBUG \
ghcr.io/wolfeitz/burlymcp:main


### 整合问题

**打开WebUI集成问题:**```bash
# Test MCP endpoint directly
curl -X POST http://localhost:9400/mcp \
-H 'content-type: application/json' \
-d '{"id":"test","method":"list_tools","params":{}}' | jq

# Verify response format
# Should return: {"ok": true, "result": {"data": {"tools": [...]}, ...}, "metrics": {...}, "meta": {...}}

# Test tool execution
curl -X POST http://localhost:9400/mcp \
-H 'content-type: application/json' \
-d '{"id":"test","method":"call_tool","name":"disk_space","args":{}}' | jq

下游系统兼容性:```bash

Test both request formats

Format 1: Direct args

curl -X POST http://localhost:9400/mcp \
-H 'content-type: application/json' \
-d '{"id":"1","method":"call_tool","name":"disk_space","args":{}}'

Format 2: Params wrapper

curl -X POST http://localhost:9400/mcp \
-H 'content-type: application/json' \
-d '{"id":"1","method":"call_tool","params":{"name":"disk_space","args":{}}}'

Both should return equivalent responses


### 获取帮助

**收集诊断信息:**```bash
#!/bin/bash
# diagnostic-info.sh - Collect system information for support

echo "=== System Information ==="
uname -a
docker --version
echo

echo "=== Container Status ==="
docker ps -a | grep burlymcp
echo

echo "=== Container Logs (last 50 lines) ==="
docker logs --tail 50
echo

echo "=== Health Check ==="
curl -s http://localhost:9400/health | jq 2>/dev/null || curl -s http://localhost:9400/health
echo

echo "=== Network Configuration ==="
docker port
netstat -tlnp | grep 9400
echo

echo "=== File Permissions ==="
ls -la /var/run/docker.sock 2>/dev/null || echo "Docker socket not found"
getent group docker 2>/dev/null || echo "Docker group not found"
echo

echo "=== Environment ==="
docker exec  env | grep -E "(GOTIFY|BLOG|DOCKER|LOG|RATE)" | sort

常见解决方案总结:

  • 端口冲突:使用 -p 9401:9400 或不同端口
  • 权限问题:确保UID 1000拥有已装载的目录
  • Docker访问:使用 --group-add $(getent group docker | cut -d: -f3)
  • 网络问题:检查防火墙规则和端口绑定
  • 配置错误:验证YAML语法和环境变量
  • 性能问题:设置资源限制并检查阻塞操作

支持和社区

  • 🐛 问题: GitHub 问题
  • 💬 讨论: GitHub讨论
  • 📧 安全:私下向安全部门报告安全问题@

致谢

  • 建立在 模型上下文协议 规格
  • 受安全AI系统集成需求的启发
  • 感谢开源社区提供的工具和库

⚡ 准备好赋予你的AI助手超能力了吗?立即开始使用Burly MCP!

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Burly MCP 怎么安装?

在客户端按下面的安装命令接入:docker run --rm -p 9400:9400 ghcr.io/wolfeitz/burlymcp:main。装完在客户端配置里引用同一个包或端点。

Burly MCP 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Burly MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Burly MCP 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

Burly MCP 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Burly MCP 能提供哪些能力?

资料显示约 4 个工具;能力标签包括 安全协议、Python、Claude。具体工具清单以官方文档为准。

Burly MCP 需要什么运行环境?

运行时为 Docker;属于本地进程,需要在本机装好运行环境。

Burly MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。