使用说明

Tailscale MCP服务器

一个MCP（模型上下文协议）服务器，用于使用官方的Tailscale Go客户端库v2管理Tailscale资源。该服务器通过由OpenAPI文档提供的增强的自我描述工具，提供Tailscale API的完整覆盖。

🚀 特性

此MCP服务器提供 42种综合工具 按逻辑类别组织，每个类别都有详细的描述、OAuth范围、用例和安全考虑因素：

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

尾秤_设备_列表 -列出所有带有可选详细字段的设备
尾秤_设备_组 -获取全面的设备信息
尾架_设备_尾架 -从尾网上永久移除设备
尾秤_设备_授权 -授权/取消授权设备进行访问控制
尾秤_设备_名称 -设置设备名称（影响Magic DNS）
尾秤_设备_标签 -为基于ACL的访问控制分配标签
尾秤_设备_ expire -强制设备重新认证
尾尺_设备_路线_列表 -列出子网路由和出口节点配置
尾尺_设备_路线_设置 -配置子网路由和出口节点

🔐 密钥管理（4个工具）

tailscale_keys_list -列出所有具有功能的身份验证密钥
尾尺_按键_组 -获取详细的关键信息和使用统计数据
tailscale_key_create -创建可重用、临时或预授权密钥
tailscale_key_delete -撤销身份验证密钥

👥 用户管理（8个工具）

tailscale_users_list -列出所有具有角色和状态的用户
尾秤_用户_组 -获取详细的用户资料信息
尾秤_用户_批准 -批准用户访问尾网
尾秤_用户_悬架 -暂时暂停用户访问
tailscale_user_restore -恢复暂停的用户
尾标_用户_尾标 -永久删除用户
尾秤_触点_get -获取尾网接触偏好
尾秤_联系_更新 -更新通知的联系信息

🌐 DNS管理（9个工具）

tailscale_dns_nameservers_get -获取已配置的DNS名称服务器
tailscale_dns_nameservers_set -设置自定义DNS名称服务器
tailscale_dns_参考参数_get -获取MagicDNS和DNS首选项
尾秤_dns_参考值_set -配置MagicDNS和DNS行为
tailscale_dns_archpaths_get -获取DNS搜索域后缀
tailscale_dns_searchpaths_set -为短名称设置DNS搜索路径
tailscale_policy_get -获取当前ACL策略文件（HuJSON）
tailscale_policy设置 -使用安全规则更新ACL策略
tailscale_policy_validate -部署前验证策略文件

🔗 高级功能（12个工具）

tailscale_webhooks_列表 -列出事件通知的webhook端点
tailscale_webhook_创建 -创建用于外部集成的webhooks
tailscale_webhook_获取 -获取webhook配置和统计信息
tailscale_webhook_删除 -删除webhook端点
尾秤_锁紧配置_get -获取审核日志流配置
tailscale_logging_network_get -获取网络流日志配置
尾架_设备_成本_集成_列表 -列出安全态势集成
规模_设备_成本_集成_创建 -创建姿势提供者集成
尾秤_设备_成本_集成_组 -获取姿势整合详细信息
尾距_设备_成本_集成_删除 -删除姿势集成
尾秤_尾网_设置_组 -获得全面的尾网设置
尾秤_尾网_设置_更新 -更新尾网配置

📦 安装

先决条件

具有API访问权限的有效Tailscale帐户
Tailscale API密钥或OAuth客户端凭据
选择一种部署方法：
- 码头工人 （推荐）-Docker和Docker Compose
- 二进制 -转到1.24或更高版本
- 源 -转到1.24或更高版本+Git

🐳 Docker部署（推荐）

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

Docker快速入门

# Using API key authentication
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

# Using OAuth authentication
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（推荐）

克隆存储库：

git clone <repository-url>
cd mcp

创建环境文件：

# Copy example environment file
cp .env.example .env

# Edit with your credentials
vim .env

启动服务器：

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

在本地构建Docker镜像

# Build the image
docker build -t tailscale-mcp-server:local .

# Run with local image
docker run -d \
  --name tailscale-mcp-server \
  -e TAILSCALE_API_KEY="tskey-api-..." \
  tailscale-mcp-server:local

从源代码构建

git clone <repository-url>
cd mcp

安装依赖项：

go mod tidy

构建服务器：

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

二进制安装

# Download and install directly
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"  # Optional, defaults to "-"

OAuth身份验证（推荐用于应用程序）

export TAILSCALE_CLIENT_ID="your-oauth-client-id"
export TAILSCALE_CLIENT_SECRET="your-oauth-client-secret"
export TAILSCALE_TAILNET="your-tailnet-name"  # Optional, defaults to "-"

身份验证优先级

如果两者都有 TAILSCALE_CLIENT_ID 和 TAILSCALE_CLIENT_SECRET 如果已设置，则使用OAuth
否则，API密钥身份验证与 TAILSCALE_API_KEY

🚀 用法

运行服务器

# Using API key authentication
TAILSCALE_API_KEY="tskey-api-..." ./tailscale-mcp-server

# Using OAuth authentication
TAILSCALE_CLIENT_ID="..." TAILSCALE_CLIENT_SECRET="..." ./tailscale-mcp-server

# With custom tailnet
TAILSCALE_API_KEY="tskey-api-..." TAILSCALE_TAILNET="mycompany.com" ./tailscale-mcp-server

MCP客户端集成

Claude代码集成

使用Docker：

# Add Docker container to Claude Code
claude mcp add tailscale docker run --rm -i \
  -e TAILSCALE_API_KEY="tskey-api-..." \
  tailscale-mcp-server:latest

使用二进制：

# Add binary to 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 - Quick run with environment validation
./scripts/quick-run.sh

# PowerShell/Windows - Quick run with environment validation
.\scripts\quick-run.ps1

# Custom image
./scripts/quick-run.sh ghcr.io/myuser/tailscale-mcp-server:v1.0.0

注册表发布：

# Bash - Build and push to registry
./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 - Build and push to registry
.\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容器管理

# Check container status
docker ps | grep tailscale-mcp-server

# View container logs
docker logs tailscale-mcp-server

# Restart container
docker restart tailscale-mcp-server

# Update to latest image
docker pull tailscale-mcp-server:latest
docker stop tailscale-mcp-server
docker rm tailscale-mcp-server
# Then run with new image

📚 工具示例

设备管理

// List all devices with detailed information
{
  "name": "tailscale_devices_list",
  "arguments": {
    "fields": "all"
  }
}

// Get specific device details
{
  "name": "tailscale_device_get",
  "arguments": {
    "device_id": "device-id-here",
    "fields": "all"
  }
}

// Authorize a device
{
  "name": "tailscale_device_authorize",
  "arguments": {
    "device_id": "device-id-here",
    "authorized": true
  }
}

// Set device tags for ACL-based access control
{
  "name": "tailscale_device_set_tags",
  "arguments": {
    "device_id": "device-id-here",
    "tags": ["tag:server", "tag:production"]
  }
}

密钥管理

// Create a reusable, preauthorized key with tags
{
  "name": "tailscale_key_create",
  "arguments": {
    "reusable": true,
    "ephemeral": false,
    "preauthorized": true,
    "description": "CI/CD deployment key",
    "tags": ["tag:ci", "tag:automated"],
    "expiry_seconds": 86400
  }
}

// List all authentication keys
{
  "name": "tailscale_keys_list",
  "arguments": {}
}

DNS配置

// Set custom DNS nameservers
{
  "name": "tailscale_dns_nameservers_set",
  "arguments": {
    "nameservers": ["8.8.8.8", "8.8.4.4", "1.1.1.1"]
  }
}

// Enable MagicDNS for easy device connectivity
{
  "name": "tailscale_dns_preferences_set",
  "arguments": {
    "magic_dns": true
  }
}

// Set DNS search paths for short hostnames
{
  "name": "tailscale_dns_searchpaths_set",
  "arguments": {
    "search_paths": ["company.com", "internal.local"]
  }
}

策略管理

// Get current ACL policy
{
  "name": "tailscale_policy_get",
  "arguments": {}
}

// Validate policy before applying
{
  "name": "tailscale_policy_validate",
  "arguments": {
    "policy": "{\n  \"acls\": [\n    {\n      \"action\": \"accept\",\n      \"src\": [\"tag:server\"],\n      \"dst\": [\"tag:database:5432\"]\n    }\n  ]\n}"
  }
}

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

Webhooks & 集成

// Create webhook for device events
{
  "name": "tailscale_webhook_create",
  "arguments": {
    "endpoint_url": "https://your-app.com/webhook",
    "subscriptions": ["device.created", "device.deleted", "user.approved"]
  }
}

// Create device posture integration
{
  "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                 # Entry point and server setup
├── internal/
│   ├── config/                 # Configuration management
│   ├── client/                 # Tailscale client wrapper
│   └── handlers/               # MCP request handlers
├── pkg/
│   └── tools/                  # Tool implementations
│       ├── devices.go          # Device management (9 tools)
│       ├── keys.go             # Key management (4 tools)
│       ├── users.go            # User & contact management (8 tools)
│       ├── dns.go              # DNS & policy management (9 tools)
│       └── additional.go       # Advanced features (12 tools)
├── tailscale_api_docs/         # OpenAPI documentation
├── .gitignore                  # Git ignore rules
├── LICENSE.md                  # MIT License
└── README.md                   # This file

关键设计原则

模块化：每个工具类别都组织在单独的文件中
自描述的：工具包括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 - 网钩管理
logging:read -日志配置访问
posture:read / posture:write -设备姿态管理
settings:read / settings:write -尾网设置

安全最佳实践

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

🛠️ 发展

添加新工具

识别OpenAPI端点 在……里面 tailscale_api_docs/tailscaleapi.yaml
选择合适的文件 在……里面 pkg/tools/ 基于功能
添加工具定义 在 RegisterTools 方法：

tool := mcp.NewTool(
    "tailscale_new_tool",
    mcp.WithDescription("Detailed description with OAuth scope and use cases"),
    mcp.WithString("param", mcp.Description("Parameter description"), mcp.Required()),
)
mcpServer.AddTool(tool, dt.NewToolHandler)

实现处理函数 遵循现有模式
彻底测试 并更新文档

增强工具说明

所有工具包括：

详细功能 描述
OAuth作用域 需求
用例以及示例
安全注意事项
Tailscale文档链接

测试

# Run all tests
go test ./...

# Run tests with race detection
go test -race ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

为不同平台构建

使用Go Build

# Linux
GOOS=linux GOARCH=amd64 go build -o tailscale-mcp-server-linux ./cmd

# macOS
GOOS=darwin GOARCH=amd64 go build -o tailscale-mcp-server-macos ./cmd

# Windows
GOOS=windows GOARCH=amd64 go build -o tailscale-mcp-server.exe ./cmd

使用Docker多平台构建

# Build for multiple architectures
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t tailscale-mcp-server:latest --push .

# Build for specific platform
docker build --platform linux/amd64 -t tailscale-mcp-server:amd64 .
docker build --platform linux/arm64 -t tailscale-mcp-server:arm64 .

📊 监测和可观察性

内置日志

服务器为以下内容提供结构化日志记录：

身份验证尝试
API请求和响应
错误条件
性能指标

与Tailscale集成

在Tailscale管理控制台中监控API的使用情况
跟踪OAuth令牌使用情况和刷新周期
审查安全合规性审计日志

🐳 Docker功能

安全

多阶段构建 最小攻击面
刮擦基础图像 （最终图像小于20MB）
非root用户 执行（UID 65534）
只读文件系统 支持
没有新特权 安全选项
能力下降 增强安全性

演出

优化二进制 使用静态链接
资源限制 （默认128MB RAM，0.5 CPU）
健康检查 用于集装箱监控
平滑关闭 处理

生产就绪

自动重启 失败时
结构化日志记录 转到stdout/stderr
基于环境的配置
多架构支持 （AMD64、ARM64）

监控

# View real-time logs
docker logs -f tailscale-mcp-server

# Check health status
docker inspect --format='{{.State.Health.Status}}' tailscale-mcp-server

# Monitor resource usage
docker stats tailscale-mcp-server

🔗 依赖项

tailscale.com/client/tailscale/v2 -官方Tailscale Go客户端库
github/mark3labs/mcp-go -Go的MCP协议实现
golang.org/x/oauth2 -OAuth 2.0客户端库
标准Go库 -JSON、HTTP、上下文、日志

📄 许可证

该项目根据MIT许可证获得许可。看许可证.md 了解详情。

🤝 贡献

欢迎投稿！请确保所有新工具包括：

完成输入验证 带有正确的错误信息
全面的错误处理 对于所有故障情况
详细说明 遵循OpenAPI文档模式
JSON响应格式 与现有工具一致
OAuth作用域规范 在工具描述中
单元测试 核心功能
文档更新 在这个README中

开发工作流程

分叉存储库
创建要素分支： git checkout -b feature/new-tool
通过测试实现您的更改
运行测试套件： go test ./...
根据需要更新文档
提交一个带有明确描述的拉取请求

📚 资源

Tailscale API文档 -API官方参考
MCP协议规范 -MCP协议详细信息
Tailscale知识库 -全面的指南和教程
Go客户端库文档 -官方Go客户端文档

🆘 支持

问题：在GitHub上报告错误和请求功能
文档：请参阅Tailscale知识库
社区：加入Tailscale社区论坛

由以下材料制成❤️ 对于Tailscale和MCP社区。该服务器提供了最全面的Tailscale MCP集成，具有由官方OpenAPI文档支持的自我描述工具。