Tailscale MCP

🚀 Tailscale MCP Server

このサーバーは、最新のModel Context Protocol (MCP)を採用しており、TailscaleのCLIコマンドとREST APIとシームレスに統合することができます。標準化されたインターフェースを通じて、自動化されたネットワーク管理と監視を可能にします。

📦 利用可能なパッケージ

• NPM: @hexsleeves/tailscale-mcp-server
• Docker Hub: hexsleeves/tailscale-mcp-server
• GitHub Container Registry: 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 Container Registry (推奨)
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 Desktop

Claude Desktopの設定 (~/.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
# .envをTailscaleの資格情報で編集

# ビルドして実行
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                # クイックQA (型チェック + 単体テスト + リント)
npm run qa:full           # 完全なQA (すべてのテスト + チェック)
npm run typecheck         # TypeScriptバリデーション

# ツール
npm run inspector         # MCPインスペクターでテスト

ローカルClaude Desktop設定

{
  "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ファイルを参照してください。

サポート

• Issues - バグレポートと機能リクエスト
• Discussions - 質問とコミュニティサポート
• MCPドキュメント - MCPについて詳しく学ぶ

変更履歴

バージョン履歴と更新については、CHANGELOG.mdを参照してください。