Tailscale MCP

🚀 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"
      ]
    }
  }
}

環境變量

* 基於 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 管理
• 設備標籤
• 網絡鎖定操作

🤝 貢獻

1. 分叉倉庫
2. 創建功能分支：git checkout -b feature/amazing-feature
3. 進行更改並添加測試
4. 運行質量檢查：npm run qa:full
5. 提交更改：git commit -m 'Add amazing feature'
6. 推送到分支：git push origin feature/amazing-feature
7. 打開拉取請求

開發指南

• 所有新代碼使用 TypeScript
• 添加 Zod 模式進行輸入驗證
• 為新工具包含測試（請參閱 測試指南）
• 遵循現有的模塊化架構
• 為新功能更新文檔

貢獻者資源

• 測試策略 - 如何編寫和運行測試
• CI/CD 工作流 - 瞭解自動化管道
• Docker 開發 - 基於容器的開發工作流

📄 許可證

本項目採用 MIT 許可證，請參閱 LICENSE 文件瞭解詳細信息。

📞 支持

• 問題反饋 - 報告錯誤和提出功能請求
• 討論區 - 提問和獲取社區支持
• MCP 文檔 - 瞭解更多關於 MCP 的信息

📜 更新日誌

請參閱 CHANGELOG.md 瞭解版本歷史和更新信息。