JinDaGe - tailscale-mcp MCP Details

article

README

🚀 Tailscale MCP Server

Tailscale MCP Server 是一个现代化的模型上下文协议（Model Context Protocol，MCP）服务器，它与 Tailscale 的 CLI 命令和 REST API 实现了无缝集成，能够通过标准化接口实现自动化网络管理和监控。

📦 可用软件包

NPM：@hexsleeves/tailscale-mcp-server
Docker Hub：hexsleeves/tailscale-mcp-server
GitHub 容器注册表：ghcr.io/hexsleeves/tailscale-mcp-server

✨ 主要特性

设备管理：列出、授权、取消授权和管理 Tailscale 设备
网络操作：连接/断开连接、管理路由和监控网络状态
安全控制：管理访问控制列表（ACL）、设备标签和网络锁定设置
现代架构：采用 TypeScript 和 Zod 验证的模块化工具系统
CLI 集成：与 Tailscale CLI 命令直接集成
API 集成：支持 REST API 进行高级操作

📚 详细文档

本项目包含按领域组织的全面文档：

🔧 CI/CD 工作流 - GitHub Actions、测试管道和自动化发布
🧪 测试策略 - 单元测试、集成测试和测试最佳实践
🐳 Docker 指南 - 容器使用、开发工作流和部署策略

🚀 快速开始

选项 1：NPX（推荐）

无需安装直接运行：

# 显式包语法（最可靠）
npx --package=@hexsleeves/tailscale-mcp-server tailscale-mcp-server

# 或者全局安装
npm install -g @hexsleeves/tailscale-mcp-server
tailscale-mcp-server

选项 2：Docker

# GitHub 容器注册表（推荐）
docker run -d \
  --name tailscale-mcp \
  -e TAILSCALE_API_KEY=your_api_key \
  -e TAILSCALE_TAILNET=your_tailnet \
  ghcr.io/hexsleeves/tailscale-mcp-server:latest

# 或者使用 Docker Compose
docker-compose up -d

📖 有关详细的 Docker 使用、开发工作流和部署策略，请参阅 Docker 指南

🛠️ 配置

Claude 桌面端

添加到您的 Claude 桌面端配置文件（~/.claude/claude_desktop_config.json）：

使用 NPX（推荐）

{
  "mcpServers": {
    "tailscale": {
      "command": "npx",
      "args": [
        "--package=@hexsleeves/tailscale-mcp-server",
        "tailscale-mcp-server"
      ],
      "env": {
        "TAILSCALE_API_KEY": "your-api-key-here",
        "TAILSCALE_TAILNET": "your-tailnet-name"
      }
    }
  }
}

使用 Docker

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

环境变量

| 属性 | 详情 | 是否必需 | 默认值 | | ---- | ---- | ---- | ---- | | TAILSCALE_API_KEY | Tailscale API 密钥 | 是* | - | | TAILSCALE_TAILNET | Tailscale 网络名称 | 是* | - | | TAILSCALE_API_BASE_URL | API 基础 URL | 否 | https://api.tailscale.com | | LOG_LEVEL | 日志级别（0 - 3） | 否 | 1（INFO） | | MCP_SERVER_LOG_FILE | 服务器日志文件路径 | 否 | - |

* 基于 API 的操作需要。CLI 操作无需 API 凭证即可工作。

💻 可用工具

设备管理

list_devices - 列出 Tailscale 网络中的所有设备
device_action - 对特定设备执行操作（授权、取消授权、删除、过期密钥）
manage_routes - 启用或禁用设备的路由

网络操作

get_network_status - 从 Tailscale CLI 获取当前网络状态
connect_network - 连接到 Tailscale 网络
disconnect_network - 断开与 Tailscale 网络的连接
ping_peer - 对对等设备执行 ping 操作

系统信息

get_version - 获取 Tailscale 版本信息
get_tailnet_info - 获取详细的网络信息

💻 开发

快速设置

# 克隆并设置
git clone https://github.com/HexSleeves/tailscale-mcp-server.git
cd tailscale-mcp-server
npm install

# 设置环境
cp .env.example .env
# 使用您的 Tailscale 凭证编辑 .env

# 构建并运行
npm run build
npm start

开发命令

# 开发工作流
npm run dev:direct        # 使用 tsx 进行快速开发
npm run dev:watch         # 更改时自动重建
npm run build:watch       # 监视文件更改并构建

# 测试
npm test                  # 运行所有测试
npm run test:unit         # 仅运行单元测试
npm run test:integration  # 运行集成测试（需要 Tailscale CLI）
npm run test:watch        # 监视模式

# 质量保证
npm run qa                # 快速质量保证（类型检查 + 单元测试 + 代码检查）
npm run qa:full           # 全面质量保证（所有测试 + 检查）
npm run typecheck         # TypeScript 验证

# 工具
npm run inspector         # 使用 MCP Inspector 进行测试

本地 Claude 桌面端配置

{
  "mcpServers": {
    "tailscale-dev": {
      "command": "node",
      "args": ["/path/to/your/tailscale-mcp-server/dist/index.js"],
      "env": {
        "TAILSCALE_API_KEY": "your-api-key-here",
        "TAILSCALE_TAILNET": "your-tailnet-name",
        "LOG_LEVEL": "0"
      }
    }
  }
}

📖 有关全面的开发指南、测试策略和 CI/CD 信息：

测试文档 - 单元测试、集成测试和覆盖率

Docker 开发 - 基于容器的开发工作流

CI/CD 工作流 - GitHub Actions、自动化和发布

项目结构

src/
├── server.ts              # 主服务器实现
├── tools/                 # 模块化工具定义
├── tailscale/             # Tailscale 集成
├── types.ts               # 类型定义
├── logger.ts              # 日志实用工具
└── index.ts               # 入口点

添加新工具

在 src/tools/ 中创建一个工具模块，并在 src/server.ts 中注册它。参考现有工具，了解如何使用 Zod 模式和 TypeScript 实现模块化架构。

调试

# 启用调试日志
export LOG_LEVEL=0
export MCP_SERVER_LOG_FILE=debug-{timestamp}.log

# 查看日志
tail -f logs/debug-*.log

📄 API 参考

工具类别

设备工具

设备列表和过滤
设备授权管理
每个设备的路由管理

网络工具

网络状态监控
连接管理
对等连接测试

安全工具

ACL 管理
设备标签
网络锁定操作

🤝 贡献

分叉仓库
创建功能分支：git checkout -b feature/amazing-feature
进行更改并添加测试
运行质量检查：npm run qa:full
提交更改：git commit -m 'Add amazing feature'
推送到分支：git push origin feature/amazing-feature
打开拉取请求

开发指南

所有新代码使用 TypeScript
添加 Zod 模式进行输入验证
为新工具包含测试（请参阅测试指南）
遵循现有的模块化架构
为新功能更新文档

贡献者资源

测试策略 - 如何编写和运行测试
CI/CD 工作流 - 了解自动化管道
Docker 开发 - 基于容器的开发工作流

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 文件了解详细信息。

📞 支持

问题反馈 - 报告错误和提出功能请求
讨论区 - 提问和获取社区支持
MCP 文档 - 了解更多关于 MCP 的信息

📜 更新日志

请参阅 CHANGELOG.md 了解版本历史和更新信息。

tailscale-mcp