AI导哈

Syncthing MCP服务器

一个为Syncthing设计的MCP服务器，提供AI助手对Syncthing REST API的读写和控制访问，专注于复制感知功能。

  • by Groupthink-dev
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 piersdd/syncthing-mcp

使用说明

同步刀片mcp

MCP（模型上下文协议）服务器 同步 --开源连续文件同步工具。

专门为人工智能助手（Claude等）提供对Syncthing的REST API的读取和控制访问，重点是 复制意识：了解哪些文件夹在设备之间完全复制，以便您可以自信地回收本地磁盘空间。

主要特点

  • 令牌高效输出 --默认情况下压缩JSON； concise=false 有关完整详细信息
  • 多实例 --从单个服务器管理多个Syncthing节点
  • 写门控 --变异工具需要 SYNCTHING_WRITE_ENABLED=true；破坏性操作还需要 confirm=true
  • 复制分析 --可以安全地删除标志和可回收空间计算
  • Syncthing v2.x兼容 -针对v2.0.x REST API进行测试
  • HTTP传输 --具有承载令牌身份验证的流式HTTP，Cloudflare隧道支持
  • 技能.md --LLM技能指南，优化工具使用

工具（共39个）

实例管理

工具 描述 突变
syncthing_list_instances 列出所有配置的实例，探测可用性 否

系统状态和监控

工具 描述 突变
syncthing_system_status 设备ID、名称、正常运行时间、版本 否
syncthing_list_folders 所有包含类型和设备计数的文件夹 否
syncthing_list_devices 所有具有连接状态的设备 否
syncthing_connections 活动连接详细信息 否
syncthing_device_stats 每台设备统计数据（最后一次显示，持续时间） 否
syncthing_system_errors 最近的系统错误和警告 否
syncthing_clear_errors 清除系统错误日志 是
syncthing_system_log 最近的日志条目 否
syncthing_recent_changes 最近的文件更改事件（本地+远程） 否
syncthing_health_summary 带有警报的单次通话健康状况概述 否
syncthing_check_upgrade 检查是否有更新的Syncthing版本 否

文件夹状态和复制

工具 描述 突变
syncthing_folder_status 详细的文件夹指标（昂贵的通话） 否
syncthing_folder_completion 文件夹的每个设备完成百分比 否
syncthing_replication_report 所有文件夹：可安全删除+可回收空间 否
syncthing_folder_errors 文件夹的当前同步错误 否

设备状态

工具 描述 突变
syncthing_device_completion 设备的聚合完成情况 否

文件夹操作

工具 描述 突变
syncthing_scan_folder 立即触发重新扫描 是
syncthing_pause_folder 暂停文件夹（防止删除传播） 是
syncthing_resume_folder 恢复暂停的文件夹 是

文件级查询

工具 描述 突变
syncthing_browse_folder 浏览文件夹内容（数据库中的目录列表） 否
syncthing_file_info 特定文件的详细信息 否
syncthing_folder_need 此文件夹需要的文件不同步（分页） 否
syncthing_remote_need 远程设备需要我们提供的文件（分页） 否

冲突解决

工具 描述 突变
syncthing_override_folder 覆盖远程更改（仅发送文件夹） 是
syncthing_revert_folder 还原本地更改（仅接收文件夹） 是

配置突变：挂起的设备和文件夹

工具 描述 突变
syncthing_pending_devices 列出待处理的设备连接请求 否
syncthing_pending_folders 列出待定的文件夹共享优惠 否
syncthing_accept_device 接受挂起的设备 是
syncthing_reject_device 取消挂起的设备请求 是
syncthing_accept_folder 接受待定的文件夹报价 是
syncthing_reject_folder 取消挂起的文件夹优惠 是

配置变异：重新启动并忽略模式

工具 描述 突变
syncthing_restart_required 检查配置更改是否需要重新启动 否
syncthing_restart 重新启动Syncthing服务 是
syncthing_get_ignores 获取文件夹的.stignore模式 否
syncthing_set_ignores 为文件夹设置.stignore模式 是
syncthing_get_default_ignores 获取默认忽略模式 否
syncthing_set_default_ignores 设置默认忽略模式 是

写安全

除非环境变量 SYNCTHING_WRITE_ENABLED=true 已设置。默认情况下，该门处于关闭状态。

破坏性或破坏性操作还需要 confirm=true 在 调用自身，并显示拒绝消息，解释操作将执行什么操作：

工具 为什么需要确认
syncthing_override_folder 将本地状态推送到远程编辑之上——远程更改在整个集群范围内被丢弃
syncthing_revert_folder 放弃仅接收文件夹上的本地更改
syncthing_restart 停止守护进程并中断所有活动的同步传输
syncthing_accept_device 允许挂起的设备进入群集中
syncthing_accept_folder 开始将远程文件夹的内容同步到本地磁盘
syncthing_set_ignores 替换文件夹的全部内容 .stignore 图案集

代币效率

所有读取工具默认为 concise=true，生成具有最少字段的紧凑JSON，以及 短设备ID。集 concise=false 有关调试时的完整详细信息。

模式 输出样式 用例
concise=true （默认） 压缩JSON，短ID，基本字段 正常操作
concise=false 漂亮的JSON，完整的设备ID，所有字段 调试，原始数据

大型响应会自动截断为25000个字符，并附有使用指南 分页或过滤器。

看 技能.md 获取完整的LLM技能指南。

项目结构

syncthing-blade-mcp/
├── src/syncthing_mcp/
│   ├── __init__.py          # Package version
│   ├── __main__.py          # Entry point (stdio + HTTP transport)
│   ├── auth.py              # Bearer token middleware
│   ├── client.py            # SyncthingClient (HTTP methods + error handling)
│   ├── formatters.py        # Token-efficient formatting layer
│   ├── models.py            # Pydantic input models (ReadParams / WriteParams)
│   ├── registry.py          # Multi-instance registry from env vars
│   ├── server.py            # FastMCP server + lifespan
│   └── tools/
│       ├── system.py        # System status, health, errors, log, restart, upgrade
│       ├── folders.py       # Folder status, completion, replication, file queries
│       ├── devices.py       # Device listing, completion, connections, stats
│       ├── config.py        # Pending accept/reject, ignore patterns
│       └── instances.py     # Instance listing, folder listing
├── tests/                   # Tests with respx HTTP mocking
├── SKILL.md                 # LLM skill guide
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml       # Traefik reverse proxy (HTTPS/ACME)
└── docker-compose.tunnel.yml # Cloudflare Tunnel (zero-trust)

多实例支持

通过设置以下参数同时连接到多个Syncthing节点 SYNCTHING_INSTANCES 带有JSON对象的环境变量：

{
  "mini":  {"url": "http://mini.local:8384",  "api_key": "abc123"},
  "tn-sb": {"url": "http://tn-sb.local:8384", "api_key": "def456"},
  "tn-mr2": {"url": "http://tn-mr2.local:8384", "api_key": "ghi789"}
}

每个工具都接受一个可选 instance 参数以针对特定节点。当只配置一个实例时，可以省略该参数。

Claude桌面配置（多实例）

{
  "mcpServers": {
    "syncthing": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/syncthing-blade-mcp",
        "run", "python", "-m", "syncthing_mcp"
      ],
      "env": {
        "SYNCTHING_INSTANCES": "{\"mini\":{\"url\":\"http://mini.local:8384\",\"api_key\":\"abc123\"},\"tn-sb\":{\"url\":\"http://tn-sb.local:8384\",\"api_key\":\"def456\"}}"
      }
    }
  }
}

安全移除工作流程

  1. 跑 syncthing_replication_report --查看显示的文件夹 safe: true
  2. 确认完全复制的远程设备是您所期望的设备
  3. syncthing_pause_folder --阻止Syncthing传播本地更改
  4. 删除Syncthing之外的本地数据
  5. 通过Syncthing web UI从该设备的配置中删除文件夹（可选）

重要提示： 删除前始终暂停。在一个 sendreceive 文件夹，不暂停删除文件会将删除操作传播到所有连接的设备。

这 safe 标志要求：至少有一个远程设备100%完成 remoteState: valid，中的文件夹 idle 状态，文件夹未暂停。这是故意保守的。

设置

先决条件

  • Python 3.11+
  • 紫外线 （推荐）或pip
  • 具有API访问权限的正在运行的Syncthing实例

安装

git clone https://github.com/piersdd/syncthing-blade-mcp.git
cd syncthing-blade-mcp
uv sync

获取Syncthing API密钥

打开Syncthing web UI→ 行动→ 设置→ API密钥。

配置Claude桌面（单实例）

{
  "mcpServers": {
    "syncthing": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/syncthing-blade-mcp",
        "run", "python", "-m", "syncthing_mcp"
      ],
      "env": {
        "SYNCTHING_API_KEY": "your-api-key-here",
        "SYNCTHING_URL": "http://localhost:8384"
      }
    }
  }
}

HTTP传输

流式HTTP（直接）

MCP_TRANSPORT=streamable-http MCP_AUTH_TOKEN=secret MCP_PORT=8000 syncthing-blade-mcp

Docker+Traefik（HTTPS与ACME/Let’s Encrypt）

cp .env.example .env   # edit API keys and DOMAIN
docker compose up -d

它部署在Traefik后面，带有自动Let's Encrypt TLS证书。 MCP端点位于 https://syncthing-blade-mcp.<DOMAIN>/mcp.

Docker+Cloudflare隧道（零信任，无开放端口）

cp .env.example .env   # edit API keys and CLOUDFLARE_TUNNEL_TOKEN
docker compose -f docker-compose.tunnel.yml up -d

在以下位置创建隧道 Cloudflare零信任 → 网络→ 隧道。 将隧道的公共主机名指向 http://syncthing-blade-mcp:8000. 承载令牌身份验证(MCP_AUTH_TOKEN)保护端点； /health 探测未经身份验证。

克劳德代码（远程HTTP）

{
  "mcpServers": {
    "syncthing": {
      "type": "streamable-http",
      "url": "https://syncthing-blade-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

运行测试

uv sync
uv run pytest -v

环境变量

变量 必填 默认 描述
SYNCTHING_API_KEY 是* - neneneba API键（单实例模式）
SYNCTHING_URL 没有 http://localhost:8384 基本URL（单实例模式）
SYNCTHING_INSTANCES 没有 -- JSON对象用于多实例模式
MCP_TRANSPORT 没有 stdio 运输： stdio 或 streamable-http
MCP_HOST 没有 0.0.0.0 HTTP侦听主机
MCP_PORT 没有 8000 HTTP侦听端口
MCP_AUTH_TOKEN 没有 -- HTTP传输的承载令牌
DOMAIN Traefik TLS没有 -- FQDN（docker compose.yml）
CLOUDFLARE_TUNNEL_TOKEN 无 -- 隧道令牌（docker compose.Tunnel.yml）

*除非满足以下条件，否则必须 SYNCTHING_INSTANCES 已设置。

性能说明

  • syncthing_folder_status 和 syncthing_replication_report 呼叫Syncthing /rest/db/status 端点，这是昂贵的（Syncthing端的高CPU/RAM）。在低功耗硬件上谨慎使用。
  • 复制报告生成一个 /rest/db/completion 每个远程设备每个文件夹调用。
  • syncthing_health_summary 电话 /rest/db/status 对于每个文件夹——等效成本。
  • Syncthing v2.x使用SQLite（取代LevelDB）。v1之后的首次发布→v2迁移可能很长。

许可证

麻省理工学院

相关 MCP