内容
tailscale-rmcp
`tailscale-rmcp` 是一个用 Rust 编写的 MCP 服务器和 CLI，用于通过 Tailscale REST API 管理 Tailscale 网络。
它提供了一个 MCP 工具 `tailscale` 和一个 CLI 工具 `rtailscale`。代理可以列出设备、检查路由、读取 API 密钥、ACL 策略、DNS 设置和用户，授权设备，并删除设备，当破坏性门控显式启用时。
**30 秒路径：** 设置 `TAILSCALE_API_KEY`，然后运行 `npx -y tailscale-rmcp devices --json` -> 使用 `TAILSCALE_MCP_HOST=127.0.0.1 npx -y tailscale-rmcp serve` 启动回环 HTTP -> 调用 `tools/call`，传递 `{"action":"devices"}`。
**状态：** 操作的 RMCP 上游客户端服务器。具有设备授权的写能力；设备删除需要服务器启用和调用者确认。HTTP MCP 支持回环开发模式、静态持有者令牌和通过 `lab-auth` 的 Google OAuth。
**不适用于：** 替换 Tailscale 管理控制台、绕过 Tailscale 账户权限、从一个信任边界操作多个无关的网络、存储调用者的 API 密钥、任意 WireGuard 控制或通过 MCP 工具参数传递 Tailscale API 密钥。
## 目录
- [命名](#命名)
- [功能和边界](#功能和边界)
- [安装](#安装)
- [快速入门](#快速入门)
- [客户端配置](#客户端配置)
- [运行时界面](#运行时界面)
- [MCP 工具参考](#mcp-工具参考)
- [CLI 参考](#cli参考)
- [配置](#配置)
- [身份验证](#身份验证)
- [安全和信任模型](#安全和信任模型)
- [架构](#架构)
- [分发合约](#分发合约)
- [开发](#开发)
- [验证](#验证)
- [部署](#部署)
- [故障排除](#故障排除)
- [相关服务器](#相关服务器)
- [文档](#文档)
- [许可证](#许可证)
## 命名
| 界面 | 本仓库 |
|---|---|
| 仓库 | `tailscale-rmcp` |
| Rust 包 | `tailscale-rmcp` |
| 二进制文件 / CLI | `rtailscale` |
| npm 包 | `tailscale-rmcp` |
| npm 二进制文件别名 | `tailscale-rmcp`，`rtailscale` |
| MCP 工具 | `tailscale` |
| 配置首页 | 主机上的 `~/.tailscale-mcp`，容器中的 `/data` |
| 环境前缀 | `TAILSCALE_*`，`TAILSCALE_MCP_*`，`TAILSCALE_RMCP_*` 用于 npm 启动器控制 |
该仓库、包和 npm 包使用 RMCP 家族名称。发布的二进制文件是 `rtailscale`，以避免与官方 `tailscale` CLI 冲突。
## 功能和边界
- 列出设备并检查单个设备 ID 或旧数字设备 ID。
- 读取子网路由、API 密钥、ACL 策略、DNS/MagicDNS 设置和网络用户。
- 授权设备加入网络。
- 删除设备仅当 `TAILSCALE_ALLOW_DESTRUCTIVE=true` 且调用者也提供显式确认。
| 本仓库拥有 | Tailscale 拥有 | 明确超出范围 |
|---|---|---|
| MCP/CLI 投影、请求验证、HTTP MCP 身份验证策略、响应塑形、设置检查和破坏性门控。 | 网络状态、设备身份、ACL 语义、DNS 行为、API 密钥颁发、用户成员资格和上游授权。 | 替换管理控制台、存储调用者凭证、多网络租户、任意 WireGuard 控制、超出暴露操作的策略编辑和本地 Tailscale 守护进程管理。 |
## 安装
| 路径 | 命令 | 最适合 | 备注 |
|---|---|---|---|
| npm / npx | `npx -y tailscale-rmcp --help` | 本地 MCP 客户端和快速试验。 | 从 GitHub Releases 下载匹配的 `rtailscale` 二进制文件。 |
| 发布安装程序 | `curl -fsSL https://raw.githubusercontent.com/jmagar/rtailscale/main/scripts/install.sh \| bash` | 无 Node 的主机安装。 | 为当前 Linux 主机安装 `rtailscale`。 |
| Docker / Compose | `docker compose up - | 共享 HTTP MCP 部署。 | 读取 `.env` 并暴露容器端口 `40040`。 |
| 从源代码构建 | `cargo build --release`和审计。 | 生成 `target/release/rtailscale |
| 插件 | `claude plugin installailscale` | Claude Code 本地插件设置 使用打包的设置钩子、技能和本地运行时元数据。 |
### npm / npx
在不手动安装二进制文件的情况下运行 stdio MCP 服务器或 CLI：
```bash
npx -y tailscale-rmcp --help
npx -y tailscale-rmcp mcp
npx -y tailscale-rmcp devices --json
```
npm 包在 `postinstall` 期间下载 `rtailscale`。仅在测试包装时覆盖下载行为：
| 变量 | 目的 |
|---|---|
| `TAILSCALE_RMCP_SKIP_DOWNLOAD=1` | 跳过安装后二进制文件下载。 |
| `TAILSCALE_RMCP_VERSION` 或 `TAILSCALE_RMCP_BINARY_VERSION` | 选择 GitHub Release 标签。 |
| `TAILSCALE_RMCP_REPO` | 选择用于发布下载的 GitHub 仓库。 |
| `TAILSCALE_RMCP_RELEASE_BASE_URL` | 选择自定义发布基准 URL。 |
### 从源代码构建
```bash
git clone https://github.com/jmagarcale
cd tailscale-rmcp
cargo build --./target/release/rtailscale --help
```
的 Rust 版本：1.86。
## 快速入门
### 1. 获取 Tailscale API
在 <https.tailscale.com/keys> 创建密钥。使用计划公开的最小功能。
### 2. 配置网络
```bash
export TAILSCALE_API_KEY="tskey-api-..."
export TAILSCALE_TAILNET="-" # 个人网络，或组织使用 "example.com"
```
每个 Tailscale 账户都属于一个网络。`TAILSCALE_TAILNET=-` 指向默认个人网络；组织网络通常使用组织域名。
### 3. 运行安全 CLI 调用
```bash
npx -y tailscale-rmcp devices --json
```
### 4. 启动回环 HTTP MCP
```bash
TAILSCALE_MCP_HOST=127.0.0.1 npx -y tailscale-rmcp serve
```
在另一个 shell 中：
```bash
curl -sf http://127.0.0.1:40040/health
```
### 5. 进行首次 MCP 调用
```bash
curl -s -X POST http://127.0.0.1:40040/mcp \
-H "Content 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
```json
{
"mcpServers": {
"tailscale": {
command": "npx",
"args": ["", "tailscale-rmcp", "m "env": {
"TAILSCALE_APItskey-api-...",
"TAILSCALE": "-"
}
}
}
### Claude Code HTTP
```json
{
"mcpServers": {
"tailscale": {
": "http",
"url": ".0.0.1:40040",
"headers": {
"AuthorizationBearer ${TAILSCALE_MCP_TOKEN}"
}
}
}
}
```
### Codex / Labby Gateway
通过 Labby 将 Tailscale 注册为 HTTP服务器，在共享一个长时间运行的服务器时，或 stdio 运行仅限本地使用。
```toml
[mcp_servers.tailscale]
command = "npx"
args = ["-y", "tailscale-rmcp", "m```
### 通用
```json
{
"command": "cale",
"args": ["mcp"],
env": {
"TAILSCALE_API_KEY": "tskey-api-...",
"TAILSCALE_TAILNET": "-"
}
}
```
不要将 `_API_KEY`、OAuth 机密、密码、密钥或上游持有者令牌放入 MCP参数中。使用环境变量、配置文件或 MCP 秘密存储。MCP 调用者永远不会提供凭证、令牌、密钥或秘密作为操作参数 运行时界面
| 界面 | 状态 |点 | 目的 |
|---|---:|| MCP stdio | 支持 | `rtailscp`，`npx -y tailscale-rmcp mcp` | 本地子进程 MCP。 |
| MCP HTTP | 支持 | `rt serve`，`POST /mcp` | 可流式 HTTP MCP，用于本地或共享服务器部署。 |
| CLI | 支持 | `rtailscale <command>` | 可脚本化的对齐和调试。 |
| REST API | 未发布 | N/A | Tailscale 已经拥有 REST API。 |
| Web UI | 未发布 | N/A | Tailscale管理控制台。 |
## MCP 工具参考
公开一个 MCP：`tailscale`。传递所需的 `action` 参数以选择操作。
### 读取操作
| 操作 | 描述 | 必需参数 | 可选参数 |
|---|---|---|---|
| `devices` | 列出网络中的所有设备。 | 无 | 无 |
| `device` | 返回一个设备。 | `id` | 无 |
| `device_routes` | 返回一个设备的子网路由。 | `id` | 无 |
| `keys` | 列出网络中的 API 密钥。 | 无 | 无 |
| `acl` | 返回 ACL 策略 JSON。 | 无 | 无 |
| `dns` | 返回 DNS 名称服务器、搜索路径和 MagicDNS 首选项。 | 无 | 无 |
| `users` | 列出网络用户。 | 无 | 无 |
| `help` | 返回内置操作文档。 | 无 | 无 |
### 写入操作
| 操作 | 描述 | 必需参数 | 可选参数 |
|---|---|---|---|
| `authorize_device`批准设备加入网络。 | `id` |
### 破坏性操作
| 操作 | 描述 | 必需参数 | 可选参数 |
|---|
| `delete_device` | 永久删除设备。 | `id`，`confirm=true` | 无 |
设备 ID 可以是稳定的节点 ID，例如 `n1234abc` 或旧数字设备 ID。首先使用 `action=devices` 发现 ID。
## CLI 参考文件调用与 MCP 工具相同的服务
```bash
rtailscale devices [--ailscale device <id> [--json]
routes <device-id> [--json]
rtailscale keys [--json]
rtailscale acl [--rtailscale dns [--json]
rtails [--json]
rtailscale authorize <device-id> [--json]
rtailscale delete-device <device-id> --confirm [--json]
rtailscale doctor [--json]
rtailscale setup check [--json]
rtailscale setup repair [--json]
```
所有命令当前都打印 JSON。`--json` 被接受以与 RMCP 家族的其他部分保持一致。
## 配置
主机安装程序在加载读取 `~/.tailscale-mcp/.env`。容器读取 `/data/.env`。进程环境覆盖两者。
| | 默认值 | 目的 |
|---|---| `TAILSCALE_API_KEY` | 未设置ailscale API 密钥。 |
| `TAILSCALE_TAILNET` | `-` | 网络：组织域名或个人网络的 `-`。 |
| `TAILSCALE_ALLOW_DESTRUCTIVE` | `false` | 在服务器端启用 `delete_device`。 |
| `TAILSCALE_MCP_HOST` | `0.0.0` | HTTP 绑定主机。 |
| `TAILSCALE_MCP_PORT` | `40040` | HTTP 绑定端口。 |
TAILSCALE_MCP_SERVER_NAME` | `-rmcp` | 公告的 MCP 服务器 |
| `TAILSCALE_MCP_NO_AUTH `false` | 仅在回环开发身份验证。 |
| `TAILSCALE_M` | 未设置 | HTTP MCP 的静态持有者令牌。 |
| `TAILSCALE_NOAUTH` | `false` | 信任上游网身份验证。 |
| `TAILSCALE_M_MODE` | `bearer` | `bearer` 或 `oauth`。 |
| `TAILSCALE_MCP_PUBLIC_URL` | 未设置 |发现的公共 URL。 |
| `TAILSCALE_MCP_GOOGLE_CLIENT_ID` | 未设置 | Google OAuth 客户端 ID。 |
| `TAILSCALE_MCP_GOOGLE_CLIENT_SECRET` | 未设置 OAuth 客户端密钥。 |
| `_MCP_AUTH_ADMIN_EMAIL` | 未设置 引导的管理员电子邮件。 |
| `TAILSCALE_MCP_ALLOWED_HOSTS` | 未设置 | 额外的已接受主机头值。 |
| `TAILSCALE_MCP_ALLOWED_ORIGINS` | 未设置 | 额外的已接受 CORS 来源。 |
## 身份验证
Stdio MCP 作为本地受信任的子进程运行，不使用 HTTP 身份验证。
HTTP MCP 身份验证策略：
| 状态 | 条件 | |
|---|---|---|
| 回环开发 | `TAILSCALE_MCP_HOST` 以 `127.` 开头或在回环上显式禁用身份验证 | 允许本地未经身份验证的开发。 |
| 挂者 | 非回环且具有 `TAILSCALE_MCP_TOKEN` | 需要 `Authorization: Bearer <token>` 和操作范围。 |
| 挂载 OAuth | `TAILSCALE_MCP_AUTHoauth` | 通过 `lab-auth` OAuth/JWT。 |
| 受信任网 `TAILSCALE_NOAUTH=true` | 假设反向代理或网关已经强制执行身份验证。 |
除非配置了持有者身份验证、OAuth 或 `TAILSCALE_NOAUTH=true`，否则非回环 HTTP 启动将被拒绝。
## 安全和信任模型
- Tailscale API 密钥仅从配置/环境加载。
-者选择操作和 ID，而不是上游- `` 具有双密钥互锁：`TAILSCALE_ALLOW_DESTRUCTIVE=true` 在服务器端和调用者提供的 `confirm=true`。
- 缺失的 ID 和在上游调用之前失败。
- 非回环 HTTP 部署必须使用持有者身份验证、OAuth 或受已身份验证网关。
- 此桥不隔离 Tailscale 本身。Tailscale 仍然负责 API 权限和网络状态更改。
## 架构
```text
TailscaleClient (src/tailscale.rs REST 传输 错误处理
TailscaleService (src/app.rs) 操作行为和破坏性门控
|
MCP shim (src/mcp.rs) JSON 参数 -> 服务 -> 值
CLI shim (src/cli.rs) argv -> 服务 -> stdout
```
## 分发合约
- `Cargo.toml`、`Cargo.lock`、`packages/tailscale-rmcp/package、`release-please-manifest.json `server.json` 必须同意发布的版本 GitHub Releases 发布被 npm 启动器rtailscale进制文件。
- npm 包名称为 `tailscale-rmcp`；二进制别名为 `tailscale-rmcp` 和 `rtailscale`。
- Docker/OCI 元数据使用 `ghcr.io/jmagar/rtailscale:<version>`。
- `plugins/tailscale/.mcp.json` 必须启动 `npx -y tailscale-rmcp mcp`，以便 stdio 客户端启动 MCP 传输而不是 HTTP 服务器模式。
- 根 README 是策划的。操作行为和配置默认值的真实来源是 `src/`，以及包、插件和注册表清单。
## 开发
```bash
--check
cargo test
cargo clippy -- -D warnings
cargo build --release
prefix packages/tails run check
```
## 验证
```bash
python3 /home/jmagar/workspace/soma/scripts/check-readme-guide.py README.md
npm --prefix packages/tailscale-rmcp run check
cargo check
cargo test
git diff --check
```
运行时测试：
```bash
TAILSCALE_API_KEY=tskey-api-... \
TAILSCALE_TAILNET=- \
rtailscale devices --json
```
HTTP 冒烟测试：
```bash
TAILSCALE_MCP_HOST=127.0.0.1 rtailscale serve -sf http://127.0.1:40040/health
部署
在本地开发中使用回环：
```bash
TAILSCALE_MCP_HOST=127.0.0.1 rtailscale serve
```
使用 Docker Compose 进行共享 HTTP 部署：
```bash
cp .env.example .env
docker compose up -d
```
当绑定到非回环地址时，请在经过身份验证的网关后面配置 `TAILSCALE_MCP_TOKEN`、`TAILSCALE_MCP_AUTH_MODE=oauth` 或 `TAILSCALE_NOAUTH=true`。
## 故障排除
| 症状 | 检查 |
|---|---|
| 丢失 `_KEY` | 在环境变量或 `~/.tailscale-mcp/.env` 中设置。 |
| 设备调用返回未经授权 | 在 Tailscale 管理设置中刷新 API 密钥。 |
| HTTP `/mcp` 返回未经授权 | 设置 `TAILSCALE_MCP_TOKEN` 并发送 `Authorization: Bearer <token>`。 |
| Stdio 客户端挂起或记录 JSON 错误 | 确保客户端配置运行 `tailscale-rmcp mcp`，而不是默认的 HTTP 服务器模式| `delete_device` 被拒绝 | 在服务器端设置 `_ALLOW_DESTRUCTIVE=true`，并在验证目标后传递 `confirm=true`。 |
|冲突 | 设置 `TAILSCALE_MCP_PORT` 或停止使用 `40040进程。 |
## 相关服务器
- [soma](https://github.com/jmagar/soma) - 用于提供者支持的 MCP 服务器的 RMCP。
- [unifi-rmcp](https://github.com/jmagar/run - UniFi 控制器 REST桥。
- [unraid-rmhttps://github.com/jmagar/runraid) - 用于 NAS 和服务器raid GraphQL 桥。
- [apprise-rmcp](https://githubmagar/rapprise) - 适用于多个投递后端的 Ap通知分发桥。
- [-rmcp](https://github.comar/rgotify) - Gotify 推送通知桥，用于发送、消息、应用程序和客户端。
- [arcane-rmcp](https://github.com/jmagar/rarcane) - 适用于容器和相关资源的 Arcane Docker 管理桥。
- [yarr](https://github.com/jmagar/yarr) - 媒体栈桥，用于 Sonarr、Radarr、Prowlarr、Plex 等服务。
- [ytdl-rmcp](https://github.com/j/rytdl) - 和元数据工作流服务器 [synapse-rmcp](https://github.com/jmagar/synapse 本地 Synapse 工作流侦察和通量操作。
- [cortex](https://githubmagar/cortex) - 系统日志和家庭实验室日志聚合 MCP 服务器。
- [axon](https://github.comar/axon) - R爬取、抓取、提取义搜索项目。
- [labhttps://github.com/jmagby) - 家庭实验室和 MCP 网关项目。
-umen](https://github.com/jmagar/lumen) - 本地搜索 MCP 服务器。
## 文档
- `CLAUDE.md` 是为贡献者和代理人策划的本地操作指南。
- `docs/SETUP.md` 是策划的插件/设置指南。
- `docs/OAUTH.md` 是策划的 OAuth 设置指南。
- `plugins/tailscale/skills/tailscale/SKILL.md` 是代理使用指南。
- `src/` 是当前操作、配置默认值、身份验证行为和 CLI 解析的真实来源。
- 包、插件、Docker 和注册表清单是策划的分发合约，应与上述验证命令一起检查。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器