技术文档摘要

Tailscale MCP 服务器

这是一个使用官方 Tailscale Go 客户端库 v2 来管理 Tailscale 资源的 MCP（模型上下文协议）服务器。该服务器提供了对 Tailscale API 的全面覆盖，并通过 OpenAPI 文档增强了自描述工具。

🚀 功能

此 MCP 服务器提供42个全面工具，按逻辑类别组织，每个工具都有详细的描述、OAuth 范围、用例和安全注意事项：

🖥️ 设备管理（9个工具）

• tailscale_devices_list - 列出所有设备及其可选详细字段
• tailscale_device_get - 获取设备的详细信息
• tailscale_device_delete - 永久删除尾网中的设备
• tailscale_device_authorize - 授权/取消授权设备以进行访问控制
• tailscale_device_set_name - 设置设备名称（影响 Magic DNS）
• tailscale_device_set_tags - 分配标签以基于 ACL 进行访问控制
• tailscale_device_expire - 强制设备重新认证
• tailscale_device_routes_list - 列出子网路由和出口节点配置
• tailscale_device_routes_set - 配置子网路由和出口节点

🔐 密钥管理（4个工具）

• tailscale_keys_list - 列出所有身份验证密钥及其功能
• tailscale_key_get - 获取详细密钥信息和使用统计
• tailscale_key_create - 创建可重复使用的临时或预授权密钥
• tailscale_key_delete - 撤销身份验证密钥

👥 用户管理（8个工具）

• tailscale_users_list - 列出所有用户及其角色和状态
• tailscale_user_get - 获取详细用户资料信息
• tailscale_user_approve - 批准用户访问尾网
• tailscale_user_suspend - 暂时暂停用户访问
• tailscale_user_restore - 恢复被暂停的用户
• tailscale_user_delete - 永久删除用户
• tailscale_contacts_get - 获取尾网联系人偏好设置
• tailscale_contact_update - 更新通知联系信息

🌐 DNS 管理（9个工具）

• tailscale_dns_nameservers_get - 获取配置的 DNS 名服务器
• tailscale_dns_nameservers_set - 设置自定义 DNS 名服务器
• tailscale_dns_preferences_get - 获取 MagicDNS 和 DNS 偏好设置
• tailscale_dns_preferences_set - 配置 MagicDNS 和 DNS 行为
• tailscale_dns_searchpaths_get - 获取 DNS 搜索域名后缀
• tailscale_dns_searchpaths_set - 设置短名的 DNS 搜索路径
• tailscale_policy_get - 获取当前 ACL 策略文件（HuJSON）
• tailscale_policy_set - 更新包含安全规则的 ACL 策略
• tailscale_policy_validate - 在部署前验证策略文件

🔗 高级功能（12个工具）

• tailscale_webhooks_list - 列出事件通知的 webhook 终点
• tailscale_webhook_create - 创建用于外部集成的 webhook
• tailscale_webhook_get - 获取 webhook 配置和统计
• tailscale_webhook_delete - 移除 webhook 终点
• tailscale_logging_configuration_get - 获取审计日志流配置
• tailscale_logging_network_get - 获取网络流量日志配置
• tailscale_device_posture_integrations_list - 列出安全态势集成
• tailscale_device_posture_integration_create - 创建态势提供商集成
• tailscale_device_posture_integration_get - 获取态势集成详情
• tailscale_device_posture_integration_delete - 移除态势集成
• tailscale_tailnet_settings_get - 获取完整的尾网设置
• tailscale_tailnet_settings_update - 更新尾网配置

📦 安装

先决条件

• 具有 API 访问权限的有效 Tailscale 账户
• Tailscale API 密钥或 OAuth 客户端凭证
• 选择一种部署方法：
  • Docker（推荐） - Docker 和 Docker Compose
  • 二进制 - Go 1.24 或更高版本
  • 源代码 - Go 1.24 或更高版本 + Git

🐳 Docker 部署（推荐）

运行 Tailscale MCP 服务器最简单的方法是使用 Docker：

使用 Docker 快速启动

# 使用 API 密钥认证
docker run -d \
  --name tailscale-mcp-server \
  --restart unless-stopped \
  -e TAILSCALE_API_KEY="tskey-api-..." \
  -e TAILSCALE_TAILNET="your-tailnet" \
  tailscale-mcp-server:latest

# 使用 OAuth 认证
docker run -d \
  --name tailscale-mcp-server \
  --restart unless-stopped \
  -e TAILSCALE_CLIENT_ID="your-client-id" \
  -e TAILSCALE_CLIENT_SECRET="your-client-secret" \
  -e TAILSCALE_TAILNET="your-tailnet" \
  tailscale-mcp-server:latest

Docker Compose（推荐）

1. 克隆仓库：

git clone <repository-url>
cd mcp

2. 创建环境文件：

# 复制示例环境文件
cp .env.example .env

# 编辑您的凭据
vim .env

3. 启动服务器：

# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务器
docker-compose down

本地构建 Docker 镜像

# 构建镜像
docker build -t tailscale-mcp-server:local .

# 使用本地镜像运行
docker run -d \
  --name tailscale-mcp-server \
  -e TAILSCALE_API_KEY="tskey-api-..." \
  tailscale-mcp-server:local

从源代码构建

1. 克隆仓库并导航到 MCP 目录：

git clone <repository-url>
cd mcp

2. 安装依赖项：

go mod tidy

3. 构建服务器：

go build -o tailscale-mcp-server ./cmd

二进制安装

# 直接下载并安装
go install github.com/pnocera/tailscale-mcp-server/cmd@latest

⚙️ 配置

服务器支持 API 密钥和 OAuth 认证方法，以实现最大灵活性。

环境变量

API 密钥认证（个人使用推荐）

export TAILSCALE_API_KEY="tskey-api-..."
export TAILSCALE_TAILNET="your-tailnet-name"  # 可选，默认为 "-"

OAuth 认证（应用程序推荐）

export TAILSCALE_CLIENT_ID="your-oauth-client-id"
export TAILSCALE_CLIENT_SECRET="your-oauth-client-secret"
export TAILSCALE_TAILNET="your-tailnet-name"  # 可选，默认为 "-"

认证优先级

1. 如果设置了 TAILSCALE_CLIENT_ID 和 TAILSCALE_CLIENT_SECRET，则使用 OAuth
2. 否则，使用 API 密钥认证 TAILSCALE_API_KEY

🚀 使用

运行服务器

# 使用 API 密钥认证
TAILSCALE_API_KEY="tskey-api-..." ./tailscale-mcp-server

# 使用 OAuth 认证
TAILSCALE_CLIENT_ID="..." TAILSCALE_CLIENT_SECRET="..." ./tailscale-mcp-server

# 使用自定义尾网
TAILSCALE_API_KEY="tskey-api-..." TAILSCALE_TAILNET="mycompany.com" ./tailscale-mcp-server

MCP 客户端集成

Claude Code 集成

使用 Docker：

# 将 Docker 容器添加到 Claude Code
claude mcp add tailscale docker run --rm -i \
  -e TAILSCALE_API_KEY="tskey-api-..." \
  tailscale-mcp-server:latest

使用二进制：

# 将二进制文件添加到 Claude Code
claude mcp add tailscale /path/to/tailscale-mcp-server

通用 MCP 客户端配置

使用 Docker：

{
  "mcpServers": {
    "tailscale": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TAILSCALE_API_KEY=tskey-api-...",
        "-e", "TAILSCALE_TAILNET=your-tailnet",
        "tailscale-mcp-server:latest"
      ]
    }
  }
}

使用二进制：

{
  "mcpServers": {
    "tailscale": {
      "command": "/path/to/tailscale-mcp-server",
      "env": {
        "TAILSCALE_API_KEY": "tskey-api-...",
        "TAILSCALE_TAILNET": "your-tailnet"
      }
    }
  }
}

🚀 快速部署脚本

即时设置：

# Bash/Linux/macOS - 快速运行并验证环境
./scripts/quick-run.sh

# PowerShell/Windows - 快速运行并验证环境
.\scripts\quick-run.ps1

# 自定义镜像
./scripts/quick-run.sh ghcr.io/myuser/tailscale-mcp-server:v1.0.0

注册发布：

# Bash - 构建并推送到注册表
./scripts/build-and-push.sh
./scripts/build-and-push.sh ghcr.io/myuser v1.0.0
./scripts/build-and-push.sh docker.io/myuser latest linux/amd64

# PowerShell - 构建并推送到注册表
.\scripts\build-and-push.ps1
.\scripts\build-and-push.ps1 -Registry "ghcr.io/myuser" -Tag "v1.0.0"
.\scripts\build-and-push.ps1 -Registry "docker.io/myuser" -Platform "linux/amd64"

Docker 容器管理

# 检查容器状态
docker ps | grep tailscale-mcp-server

# 查看容器日志
docker logs tailscale-mcp-server

# 重启容器
docker restart tailscale-mcp-server

# 更新到最新镜像
docker pull tailscale-mcp-server:latest
docker stop tailscale-mcp-server
docker rm tailscale-mcp-server
# 然后使用新镜像运行

📚 工具示例

设备管理

// 列出所有设备及其详细信息
{
  "name": "tailscale_devices_list",
  "arguments": {
    "fields": "all"
  }
}

// 获取特定设备的详细信息
{
  "name": "tailscale_device_get",
  "arguments": {
    "device_id": "device-id-here",
    "fields": "all"
  }
}

// 授权设备
{
  "name": "tailscale_device_authorize",
  "arguments": {
    "device_id": "device-id-here",
    "authorized": true
  }
}

// 为 ACL 基础的访问控制设置设备标签
{
  "name": "tailscale_device_set_tags",
  "arguments": {
    "device_id": "device-id-here",
    "tags": ["tag:server", "tag:production"]
  }
}

密钥管理

// 创建一个可重复使用的预授权密钥并带有标签
{
  "name": "tailscale_key_create",
  "arguments": {
    "reusable": true,
    "ephemeral": false,
    "preauthorized": true,
    "description": "CI/CD 部署密钥",
    "tags": ["tag:ci", "tag:automated"],
    "expiry_seconds": 86400
  }
}

// 列出所有身份验证密钥
{
  "name": "tailscale_keys_list",
  "arguments": {}
}

DNS 配置

// 设置自定义 DNS 名服务器
{
  "name": "tailscale_dns_nameservers_set",
  "arguments": {
    "nameservers": ["8.8.8.8", "8.8.4.4", "1.1.1.1"]
  }
}

// 启用 MagicDNS 以便轻松连接设备
{
  "name": "tailscale_dns_preferences_set",
  "arguments": {
    "magic_dns": true
  }
}

// 设置短主机名的 DNS 搜索路径
{
  "name": "tailscale_dns_searchpaths_set",
  "arguments": {
    "search_paths": ["company.com", "internal.local"]
  }
}

策略管理

// 获取当前 ACL 策略
{
  "name": "tailscale_policy_get",
  "arguments": {}
}

// 在应用前验证策略
{
  "name": "tailscale_policy_validate",
  "arguments": {
    "policy": "{\n  \"acls\": [\n    {\n      \"action\": \"accept\",\n      \"src\": [\"tag:server\"],\n      \"dst\": [\"tag:database:5432\"]\n    }\n  ]\n}"
  }
}

// 更新 ACL 策略
{
  "name": "tailscale_policy_set",
  "arguments": {
    "policy": "{\n  \"acls\": [\n    {\n      \"action\": \"accept\",\n      \"src\": [\"*\"],\n      \"dst\": [\"*:*\"]\n    }\n  ]\n}"
  }
}

Webhooks & 集成

// 为设备事件创建 webhook
{
  "name": "tailscale_webhook_create",
  "arguments": {
    "endpoint_url": "https://your-app.com/webhook",
    "subscriptions": ["device.created", "device.deleted", "user.approved"]
  }
}

// 创建设备态势集成
{
  "name": "tailscale_device_posture_integration_create",
  "arguments": {
    "provider": "crowdstrike",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "tenant_id": "your-tenant-id"
  }
}

🏗️ 架构

服务器遵循干净、模块化的架构：

├── cmd/
│   └── main.go                 # 入口点和服务器设置
├── internal/
│   ├── config/                 # 配置管理
│   ├── client/                 # Tailscale 客户端包装器
│   └── handlers/               # MCP 请求处理器
├── pkg/
│   └── tools/                  # 工具实现
│       ├── devices.go          # 设备管理（9个工具）
│       ├── keys.go             # 密钥管理（4个工具）
│       ├── users.go            # 用户及联系人管理（8个工具）
│       ├── dns.go              # DNS 及策略管理（9个工具）
│       └── additional.go       # 高级功能（12个工具）
├── tailscale_api_docs/         # OpenAPI 文档
├── .gitignore                  # Git 忽略规则
├── LICENSE.md                  # MIT 许可证
└── README.md                   # 本文档

关键设计原则

• 模块化：每个工具类别都组织在单独的文件中
• 自描述性：工具包括来自 OpenAPI 文档的全面描述
• 类型安全：通过结构化请求/响应处理实现全 Go 类型安全
• 错误容错：具有信息性消息的全面错误处理
• OAuth 准备：支持 API 密钥和 OAuth 认证

🔐 认证与安全

OAuth 范围

每个工具在其描述中指定了所需的 OAuth 范围：

• devices:read / devices:write - 设备管理
• keys:read / keys:write - 身份验证密钥管理
• users:read / users:write - 用户管理
• dns:read / dns:write - DNS 配置
• acl:read / acl:write - ACL 策略管理
• webhooks:read / webhooks:write - webhook 管理
• logging:read - 日志配置访问
• posture:read / posture:write - 设备态势管理
• settings:read / settings:write - 尾网设置

安全最佳实践

• 安全存储 API 密钥和 OAuth 凭证
• 使用环境变量存储敏感配置
• 在您的 MCP 客户端中实施适当的访问控制
• 定期轮换 API 密钥和 OAuth 凭证
• 通过 Tailscale 管理控制台监控 API 使用情况

🛠️ 开发

添加新工具

1. 识别 OpenAPI 端点在 tailscale_api_docs/tailscaleapi.yaml 中
2. 根据功能选择合适的文件在 pkg/tools/ 中
3. 在 RegisterTools 方法中添加工具定义：

tool := mcp.NewTool(
    "tailscale_new_tool",
    mcp.WithDescription("详细功能描述，包括 OAuth 范围和用例"),
    mcp.WithString("param", mcp.Description("参数描述"), mcp.Required()),
)
mcpServer.AddTool(tool, dt.NewToolHandler)

4. 按照现有模式实现处理器函数
5. 彻底测试并更新文档

增强工具描述

所有工具都包括：

• 详细的功能描述
• OAuth 范围要求
• 用例和示例
• 安全注意事项
• **链接到 Tails