Tailscale RMCP

tailscale-rmcp

通过 MCP 和命令行管理 Tailscale 设备、路由、DNS、密钥、用户和 ACL。

它提供一个 MCP 工具 tailscale，以及 rtailscale 命令行工具。Agent 可以列出设备、检查路由、读取 API 密钥、ACL 策略、DNS 设置和用户、授权设备，并在明确启用破坏性操作门控后删除设备。

30 秒上手： 设置 TAILSCALE_API_KEY，然后运行 npx -y @dinglebear/rtailscale devices --json -> 启动回环 HTTP 服务 TAILSCALE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rtailscale serve -> 使用 {"action":"devices"} 调用 tools/call。

状态： 可运行的 RMCP 上游客户端服务。支持写入设备授权；删除设备等破坏性操作需要同时获得服务端显式启用和调用方确认。HTTP MCP 支持回环开发模式、静态 Bearer 令牌，以及通过 lab-auth 使用 Google OAuth。

不适用于： 替代 Tailscale 管理控制台、绕过 Tailscale 账户权限、在同一信任边界内操作多个互不相关的 tailnet、为调用方存储 API 密钥、执行任意 WireGuard 控制，或通过 MCP 工具参数传递 Tailscale API 密钥。

目录

• 命名
• 功能与边界
• 安装
• 快速入门
• 客户端配置
• 运行时接口
• MCP 工具参考
• 命令行工具参考
• 配置
• 身份验证
• 安全与信任模型
• 架构
• 分发约定
• 开发
• 验证
• 部署
• 故障排查
• 相关服务
• 文档
• 许可证

命名

接口	本仓库中的名称
仓库	tailscale-rmcp
Rust crate	tailscale-rmcp
二进制文件 / 命令行工具	rtailscale
npm 包	@dinglebear/rtailscale
npm 二进制别名	tailscale-rmcp、rtailscale
MCP 工具	tailscale
配置目录	主机上为 ~/.tailscale-mcp，容器中为 /data
环境变量前缀	TAILSCALE_*、TAILSCALE_MCP_*、TAILSCALE_RMCP_*（用于 npm 启动器控制）

仓库、crate 和 npm 包使用 RMCP 系列名称。发布的二进制文件名为 rtailscale，以避免与官方 tailscale 命令行工具重名。

功能与边界

• 列出设备，并通过节点 ID 或旧版数字设备 ID 检查单台设备。
• 读取子网路由、API 密钥、ACL 策略、DNS/MagicDNS 设置和 tailnet 用户。
• 授权设备加入 tailnet。
• 仅当 TAILSCALE_ALLOW_DESTRUCTIVE=true 且调用方也提供明确确认时，才删除设备。
• 提供用于本地插件/运行时检查的设置和诊断命令。

本仓库负责	Tailscale 负责	明确不在范围内
MCP/命令行工具投影、请求验证、HTTP MCP 身份验证策略、响应整形、设置检查和破坏性操作门控。	Tailnet 状态、设备身份、ACL 语义、DNS 行为、API 密钥签发、用户成员关系和上游授权。	替代管理控制台、存储调用方凭据、多 tailnet 租户管理、任意 WireGuard 控制、对已公开操作以外的策略进行编辑，以及管理本地 Tailscale 守护进程。

安装

路径	命令	适用场景	说明
npm / npx	npx -y @dinglebear/rtailscale --help	本地 MCP 客户端和快速试用。	从 GitHub Releases 下载匹配的 rtailscale 二进制文件。
Release 安装程序	curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/rtailscale/main/scripts/install.sh | bash	无需 Node 的主机安装。	为当前 Linux 主机安装 rtailscale。
Docker / Compose	docker compose up -d	共享 HTTP MCP 部署。	读取 .env 并公开容器端口 40040。
从源代码构建	cargo build --release	开发和审查。	生成 target/release/rtailscale。
插件	claude plugin install plugins/tailscale	从此检出目录进行 Claude Code 本地插件设置。	附带技能、.mcp.json 和捆绑的二进制文件。不包含钩子——如果要验证环境，请自行运行 rtailscale setup check。

npm / npx

无需手动安装二进制文件，即可运行 stdio MCP 服务或 CLI：

npx -y @dinglebear/rtailscale --help
npx -y @dinglebear/rtailscale mcp
npx -y @dinglebear/rtailscale devices --json

npm 包会在 postinstall 期间下载 rtailscale。仅在测试打包时覆盖下载 行为：

变量	用途
TAILSCALE_RMCP_SKIP_DOWNLOAD=1	跳过 postinstall 二进制文件下载。
TAILSCALE_RMCP_VERSION 或 TAILSCALE_RMCP_BINARY_VERSION	选择 GitHub Release 标签。
TAILSCALE_RMCP_REPO	选择用于下载 release 的 GitHub 仓库。
TAILSCALE_RMCP_RELEASE_BASE_URL	选择自定义 release 基础 URL。

从源代码构建

git clone https://github.com/dinglebear-ai/rtailscale
cd rtailscale
cargo build --release
./target/release/rtailscale --help

最低支持的 Rust 版本：1.86。

快速开始

1. 获取 Tailscale API 密钥

在 https://login.tailscale.com/admin/settings/keys 创建 API 密钥。请根据计划公开的操作， 使用满足需求的最低权限。

2. 配置 Tailnet

export TAILSCALE_API_KEY="tskey-api-..."
export TAILSCALE_TAILNET="-"          # personal, or "example.com" for orgs

每个 Tailscale 账户都属于一个 tailnet。TAILSCALE_TAILNET=- 指向 默认个人 tailnet；组织 tailnet 通常使用组织域名。

3. 执行安全的 CLI 调用

npx -y @dinglebear/rtailscale devices --json

4. 启动回环 HTTP MCP

TAILSCALE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rtailscale serve

在另一个 shell 中：

curl -sf http://127.0.0.1:40040/health

5. 执行第一个 MCP 调用

curl -s -X POST http://127.0.0.1:40040/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"tailscale","arguments":{"action":"devices"}}}'

客户端配置

Claude Code Stdio

{
  "mcpServers": {
    "tailscale": {
      "command": "npx",
      "args": ["-y", "tailscale-rmcp", "mcp"],
      "env": {
        "TAILSCALE_API_KEY": "tskey-api-...",
        "TAILSCALE_TAILNET": "-"
      }
    }
  }
}

Claude Code HTTP

{
  "mcpServers": {
    "tailscale": {
      "type": "http",
      "url": "http://127.0.0.1:40040/mcp",
      "headers": {
        "Authorization": "Bearer ${TAILSCALE_MCP_TOKEN}"
      }
    }
  }
}

Codex / Labby Gateway

如果要共享一个长期运行的服务，请通过 Labby 将 Tailscale 注册为 HTTP 上游；如果仅在本地使用， 则直接以 stdio 方式运行。

[mcp_servers.tailscale]
command = "npx"
args = ["-y", "tailscale-rmcp", "mcp"]

通用 MCP JSON

{
  "command": "rtailscale",
  "args": ["mcp"],
  "env": {
    "TAILSCALE_API_KEY": "tskey-api-...",
    "TAILSCALE_TAILNET": "-"
  }
}

不要将 TAILSCALE_API_KEY、OAuth 密钥、密码、SSH 密钥或上游 Bearer 令牌放入 MCP 工具参数中。请使用环境变量、配置文件或 MCP 客户端的 密钥存储。MCP 调用方不会在操作参数中提供凭据、令牌、密钥或机密。

运行时接口

接口	状态	入口点	用途
MCP stdio	支持	rtailscale mcp、npx -y @dinglebear/rtailscale mcp	本地子进程 MCP 客户端。
MCP HTTP	支持	rtailscale serve、POST /mcp	用于本地或共享服务部署的 Streamable HTTP MCP。
CLI	支持	rtailscale <command>	可编写脚本的功能对等接口和调试工具。
REST API	未提供	N/A	Tailscale 已提供 REST API。
Web UI	未提供	N/A	Tailscale 已提供管理控制台。

MCP 工具参考

公开了一个 MCP 工具：tailscale。传入必需的 action 参数以 选择操作。

读取操作

操作	说明	必需参数	可选参数
devices	列出 tailnet 中的所有设备。	无	无
device	返回一台设备。	id	无
device_routes	返回一台设备的子网路由。	id	无
keys	列出 tailnet 中的 API 密钥。	无	无
acl	返回 ACL 策略 JSON。	无	无
dns	返回 DNS 名称服务器、搜索路径和 MagicDNS 首选项。	无	无
users	列出 tailnet 用户。	无	无
help	返回内置操作文档。	无	无

写入操作

操作	描述	必需参数	可选参数
authorize_device	批准设备加入 tailnet。	id	无

破坏性操作

操作	描述	必需参数	可选参数
delete_device	永久移除设备。	id、confirm=true	无

设备 ID 可以是稳定的节点 ID（例如 n1234abc），也可以是旧版数字设备 ID。先使用 action=devices 查找 ID。

CLI 参考

二进制文件调用的服务层与 MCP 工具相同：

rtailscale devices [--json]
rtailscale device <id> [--json]
rtailscale routes <device-id> [--json]
rtailscale keys [--json]
rtailscale acl [--json]
rtailscale dns [--json]
rtailscale users [--json]
rtailscale authorize <device-id> [--json]
rtailscale delete-device <device-id> --confirm [--json]
rtailscale doctor [--json]
rtailscale setup check [--json]
rtailscale setup repair [--json]
rtailscale setup plugin-hook [--no-repair] [--json]
rtailscale serve            # HTTP MCP (also the no-argument default)
rtailscale mcp              # stdio MCP

目前所有命令都会输出 JSON。为与 RMCP 系列的其他工具保持一致，也接受 --json。

配置

主机安装会在加载配置前读取 ~/.tailscale-mcp/.env。容器会读取 /data/.env。进程环境变量的优先级高于两者。

变量	默认值	用途
TAILSCALE_API_KEY	未设置	Tailscale API 密钥。
TAILSCALE_TAILNET	-	Tailnet：组织域名，或个人账户使用 -。
TAILSCALE_ALLOW_DESTRUCTIVE	false	在服务端启用 delete_device。
TAILSCALE_MCP_HOST	0.0.0.0	HTTP 绑定主机。
TAILSCALE_MCP_PORT	40040	HTTP 绑定端口。
TAILSCALE_MCP_SERVER_NAME	tailscale-rmcp	对外公布的 MCP 服务名称。
TAILSCALE_MCP_NO_AUTH	false	仅在环回地址开发时禁用身份验证。
TAILSCALE_MCP_TOKEN	未设置	用于 HTTP MCP 的静态 bearer 令牌。
TAILSCALE_NOAUTH	false	信任上游网关会强制执行身份验证。
TAILSCALE_MCP_AUTH_MODE	bearer	bearer 或 oauth。
TAILSCALE_MCP_PUBLIC_URL	未设置	用于 OAuth 发现的公共 URL。
TAILSCALE_MCP_GOOGLE_CLIENT_ID	未设置	Google OAuth 客户端 ID。
TAILSCALE_MCP_GOOGLE_CLIENT_SECRET	未设置	Google OAuth 客户端密钥。
TAILSCALE_MCP_AUTH_ADMIN_EMAIL	未设置	用于 OAuth 引导配置的管理员邮箱。
TAILSCALE_MCP_ALLOWED_HOSTS	未设置	额外接受的 Host 标头值。
TAILSCALE_MCP_ALLOWED_ORIGINS	未设置	额外接受的 CORS 来源。
TAILSCALE_MCP_HOME	平台应用数据目录	覆盖 setup 和文件日志使用的配置/日志主目录。

Tailscale API 基础 URL 不可配置；它在 src/tailscale.rs 中固定为 https://api.tailscale.com/api/v2。

身份验证

Stdio MCP 作为本地可信子进程运行，不使用 HTTP 身份验证。

HTTP MCP 身份验证策略：

状态	条件	行为
环回开发	TAILSCALE_MCP_HOST 以 127. 开头，或仅在环回地址上显式禁用身份验证	允许本地无身份验证开发。
已部署 bearer	非环回地址，且设置了 TAILSCALE_MCP_TOKEN	要求提供 Authorization: Bearer <token> 和操作范围。
已部署 OAuth	TAILSCALE_MCP_AUTH_MODE=oauth	通过 lab-auth 使用 Google OAuth/JWT。
可信网关	TAILSCALE_NOAUTH=true	假定反向代理或网关已强制执行身份验证。

除非配置了 bearer 身份验证、OAuth 或 TAILSCALE_NOAUTH=true，否则非环回 HTTP 启动会被拒绝。

安全与信任模型

• Tailscale API 密钥仅从配置/环境变量加载。
• MCP 调用方选择操作和 ID，而不是上游凭据。
• delete_device 具有双重密钥联锁： 服务端设置 TAILSCALE_ALLOW_DESTRUCTIVE=true，且调用方提供 confirm=true。
• 缺少 ID 和未知操作会在调用上游之前导致失败。
• 非环回 HTTP 部署必须使用 bearer 身份验证、OAuth 或可信的已验证身份网关。
• 此桥接不会隔离 Tailscale 本身。API 权限和 tailnet 状态变更仍由 Tailscale 负责。

架构

TailscaleClient  (src/tailscale.rs)  REST transport and API error handling
       |
TailscaleService (src/app.rs)        action behavior and destructive gates
       |
MCP shim         (src/mcp.rs)        JSON args -> service -> Value
CLI shim         (src/cli.rs)        argv -> service -> stdout

Distribution Contract

• Cargo.toml、Cargo.lock、packages/tailscale-rmcp/package.json、 .release-please-manifest.json 和 server.json 中的发布版本必须一致。
• GitHub Releases 会发布供 npm 启动器使用的 rtailscale 二进制文件。
• npm 包名为 @dinglebear/rtailscale；二进制别名为 tailscale-rmcp 和 rtailscale。
• Docker/OCI 元数据使用 ghcr.io/dinglebear-ai/rtailscale:<version>（参见 docker-compose.prod.yml）。尽管仓库现已位于 dinglebear-ai/rtailscale， 镜像路径仍使用转移前的所有者命名空间。
• plugins/tailscale/.mcp.json 必须启动 npx -y @dinglebear/rtailscale mcp，以便 stdio 客户端启动 MCP 传输，而不是 HTTP 服务。
• plugins/tailscale/ 不包含 Claude Code hooks；如果 hooks/ 目录重新出现， scripts/validate-plugin-layout.sh 会报错。
• 根目录 README 经过人工整理。操作行为和配置默认值的事实来源是 src/， 以及包、插件和注册表清单。

开发

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
npm --prefix packages/tailscale-rmcp run check

验证

just validate-plugin
npm --prefix packages/tailscale-rmcp run check
cargo check
cargo test
git diff --check

运行时冒烟测试：

TAILSCALE_API_KEY=tskey-api-... \
TAILSCALE_TAILNET=- \
rtailscale devices --json

HTTP 冒烟测试：

TAILSCALE_MCP_HOST=127.0.0.1 rtailscale serve
curl -sf http://127.0.0.1:40040/health

部署

本地开发时使用 loopback：

TAILSCALE_MCP_HOST=127.0.0.1 rtailscale serve

使用 Docker Compose 进行共享 HTTP 部署：

cp .env.example .env
docker compose up -d

绑定到非 loopback 地址时，请配置 TAILSCALE_MCP_TOKEN、 TAILSCALE_MCP_AUTH_MODE=oauth，或在经过身份验证的网关后方设置 TAILSCALE_NOAUTH=true。

故障排除

症状	检查项
缺少 TAILSCALE_API_KEY	在环境变量中或 ~/.tailscale-mcp/.env 中设置它。
设备调用返回未授权	在 Tailscale 管理设置中刷新 API 密钥。
HTTP /mcp 返回未授权	设置 TAILSCALE_MCP_TOKEN，并发送 Authorization: Bearer <token>。
Stdio 客户端挂起或记录 JSON 错误	确保客户端配置运行 tailscale-rmcp mcp，而非默认的 HTTP 服务模式。
delete_device 被拒绝	在服务端设置 TAILSCALE_ALLOW_DESTRUCTIVE=true，并在确认目标无误后传入 confirm=true。
端口冲突	设置 TAILSCALE_MCP_PORT，或停止当前占用 40040 的进程。

相关服务

• soma - 面向由提供方支持的 MCP 服务的 RMCP 运行时和脚手架。
• unifi-rmcp - UniFi 控制器 REST API 桥接服务。
• unraid - Unraid 单体仓库；unraid-rs/ 是用于 NAS 和服务器管理的 GraphQL 桥接服务。
• apprise-rmcp - 面向众多消息投递后端的 Apprise 通知分发桥接服务。
• gotify-rmcp - Gotify 推送通知桥接服务，可处理发送、消息、应用和客户端。
• arcane-rmcp - 用于容器及相关资源的 Arcane Docker 管理桥接服务。
• yarr - 面向 Sonarr、Radarr、Prowlarr、Plex 及相关服务的媒体栈桥接服务。
• ytdl-rmcp - 媒体下载和元数据工作流服务。
• synapse-rmcp - 用于 scout 和 flux 操作的本地 Synapse 工作流服务。
• cortex - Syslog 和家庭实验室日志聚合 MCP 服务。
• axon - RAG、爬取、抓取、提取和语义搜索项目。
• labby - 家庭实验室控制平面和 MCP 网关项目。
• lumen - 本地语义代码搜索 MCP 服务。

文档

• CLAUDE.md 是为贡献者和 Agent 编写的精选本地操作指南。
• docs/SETUP.md 是精选的插件／设置指南。
• docs/OAUTH.md 是精选的 OAuth 设置指南。
• plugins/tailscale/skills/tailscale/SKILL.md 是 Agent 使用指南。
• src/ 是当前操作、配置默认值、身份验证行为和 CLI 解析的事实来源。
• 软件包、插件、Docker 和注册表清单是经过整理的分发契约，应使用上述验证命令进行检查。

许可证

本项目中由 Dinglebear 编写的原创部分采用 AGPL-3.0-only 许可。对于需要 AGPL 之外许可条款的组织，可提供单独的商业许可。第三方材料仍遵循其原始许可证。请参阅 LICENSING.md。