Hatago MCP Hub

🚀 🏮 Hatago MCP Hub

Hatago (旅籠) は、現代のAIツールとMCPサーバーをつなぐ中継地点です。この軽量なハブは、Claude CodeやCodex CLIなどのツールから複数のMCPサーバーへのアクセスを一元化します。

🚀 クイックスタート

Hatago MCP Hubは、Claude Code、Codex CLI、Cursor、Windsurf、VS Codeなどのツールから複数のMCP (Model Context Protocol) サーバーへのアクセスを一元化する軽量なハブです。

✨ 主な機能

🚀 パフォーマンス (v0.0.14)

• 起動速度が8.44倍向上 - 85.66ms → 10.14ms
• パッケージサイズが17%削減 - 1.04MB → 854KB
• アーキテクチャの簡素化 - 抽象化レイヤーを介さずに直接サーバーを管理

🎯 シンプルで軽量

• ゼロコンフィグで起動 (HTTPモード) - npx @himorishige/hatago-mcp-hub serve --http
• 既存プロジェクトへの非侵入性 - プロジェクトディレクトリを汚染しません

🔌 豊富な接続性

• 複数のトランスポートサポート - STDIO / HTTP / SSE
• リモートMCPプロキシ - HTTPベースのMCPサーバーへの透過的な接続
• NPXサーバー統合 - npmパッケージのMCPサーバーを動的に管理

🏮 追加機能

設定の更新

• 手動再起動が必要 - 設定の変更にはサーバーの再起動が必要です
• 代替策:
  • プロセスマネージャ (PM2、nodemon) を使用して自動再起動を行う
  • 例: nodemon --exec "hatago serve --http" --watch hatago.config.json
  • またはPM2を使用する場合: pm2 start "hatago serve" --watch hatago.config.json
• ツールリストの動的更新 - notifications/tools/list_changed 通知をサポート

進捗通知の転送

• 子サーバーの通知転送 - notifications/progress を透過的に転送
• 長時間実行の操作をサポート - リアルタイムの進捗更新
• ローカル/リモートをサポート - 多くのMCPサーバータイプで動作

組み込みの内部リソース

• hatago://servers - 現在接続されているサーバーのJSONスナップショット (id、ステータス、タイプ、ツール、リソース、プロンプト)

拡張機能

• 環境変数の展開 - Claude Code互換の ${VAR} および ${VAR:-default} 構文をサポート
• 設定の検証 - Zodスキーマを使用した型安全な設定
• タグベースのサーバーフィルタリング - タグを使用してサーバーをグループ化およびフィルタリング
• 設定の継承 - extends フィールドを使用して基本設定を拡張し、DRY原則を適用

最小限のハブインターフェイス (IHub)

外部パッケージ (サーバー/テストユーティリティ) は、薄い IHub インターフェイスを使用して、具体的なクラスとの密結合を避けます。

import type { IHub } from '@himorishige/hatago-hub';
import { createHub } from '@himorishige/hatago-hub/node';

const hub: IHub = createHub({
  preloadedConfig: { data: { version: 1, mcpServers: {} } }
}) as IHub;
await hub.start();
hub.on('tool:called', (evt) => {
  /* metrics, logs */
});
await hub.stop();

薄いハブ用に抽出されたモジュール:

• RPCハンドラ: packages/hub/src/rpc/handlers.ts
• HTTPハンドラ: packages/hub/src/http/handler.ts

📦 インストール

クイックスタート (インストール不要)

# 設定を初期化
npx @himorishige/hatago-mcp-hub init

# STDIOモードで起動 (Claude Code用)
# 注意: STDIOでは設定ファイルのパスが必要です
npx @himorishige/hatago-mcp-hub serve --stdio --config ./hatago.config.json

# または、設定なしでHTTPモードで起動 (デモ/開発用)
npx @himorishige/hatago-mcp-hub serve --http

グローバルインストール

# グローバルにインストール
npm install -g @himorishige/hatago-mcp-hub

# hatagoコマンドで使用
hatago init
hatago serve

プロジェクトの依存関係としてインストール

# 依存関係としてインストール
npm install @himorishige/hatago-mcp-hub

# package.jsonのscriptsに追加
{
  "scripts": {
    "mcp": "hatago serve"
  }
}

💻 使用例

Claude Code、Codex CLI、Gemini CLI

STDIOモード (推奨)

Claude Code / Gemini CLI

.mcp.json に追加:

{
  "mcpServers": {
    "hatago": {
      "command": "npx",
      "args": [
        "@himorishige/hatago-mcp-hub",
        "serve",
        "--stdio",
        "--config",
        "./hatago.config.json"
      ]
    }
  }
}

Codex CLI

~/.codex/config.toml に追加:

[mcp_servers.hatago]
command = "npx"
args = ["-y", "@himorishige/hatago-mcp-hub", "serve", "--stdio", "--config", "./hatago.config.json"]

HTTPモード

Claude Code / Gemini CLI

.mcp.json に追加:

{
  "mcpServers": {
    "hatago": {
      "url": "http://localhost:3535/mcp"
    }
  }
}

Codex CLI

~/.codex/config.toml に追加:

[mcp_servers.hatago]
command = "npx"
args = ["-y", "mcp-remote", "http://localhost:3535/mcp"]

MCPインスペクタ

テストとデバッグ用:

# HTTPモードで起動
hatago serve --http --port 3535

# MCPインスペクタで接続
# エンドポイント: http://localhost:3535/mcp

MCPインスペクタ を訪問してください。

メトリクス (オプトイン)

軽量なインメモリメトリクスを有効にし、HTTPエンドポイントを公開します:

HATAGO_METRICS=1 hatago serve --http --port 3535
# その後、ここを訪問: http://localhost:3535/metrics

注意:

• メトリクスはデフォルトで無効になっており、無効の場合はほぼオーバーヘッドがありません。
• HATAGO_LOG=json の場合、JSONログが利用可能です (HATAGO_LOG_LEVEL を尊重します)。

📚 ドキュメント

• ドキュメントインデックス: docs/README.md
• 公式CLIとハブのガイド: packages/mcp-hub/README.md
• 公開ドキュメントサイト (日本語デフォルト): https://hatago.dev/ja/ — 英語: https://hatago.dev/en/

Dev.to: Hatago MCP Hubを使用したMulti-MCPの始め方 — すべてをつなぐ1つの設定

設定ガイド

• 設定ガイド
• アーキテクチャの概要
• APIリファレンス
• チーム開発のユースケース

⚙️ 設定

基本設定

hatago.config.json を作成:

{
  "$schema": "https://raw.githubusercontent.com/himorishige/hatago-mcp-hub/main/schemas/config.schema.json",
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

リモートサーバーの設定

{
  "mcpServers": {
    "deepwiki": {
      "url": "https://mcp.deepwiki.com/sse",
      "type": "sse"
    },
    "custom-api": {
      "url": "https://api.example.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

設定戦略

戦略1: タグベースのフィルタリング

単一の設定ファイルでタグを使用してサーバーをグループ化:

{
  "mcpServers": {
    "filesystem-dev": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "tags": ["dev", "local"]
    },
    "github-prod": {
      "url": "https://api.github.com/mcp",
      "type": "http",
      "tags": ["production", "github"]
    },
    "database": {
      "command": "mcp-server-postgres",
      "tags": ["dev", "production", "database"]
    }
  }
}

特定のタグで起動:

# "dev" タグが付いたサーバーのみを起動
hatago serve --tags dev

# "dev" または "test" タグが付いたサーバーを起動
hatago serve --tags dev,test

# 日本語のタグもサポート
hatago serve --tags 開発,テスト

戦略2: 設定の継承

extends フィールドを使用して環境ごとに設定を分割:

基本設定 (~/.hatago/base.config.json):

{
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

作業用設定 (./work.config.json):

{
  "extends": "~/.hatago/base.config.json",
  "logLevel": "debug",
  "mcpServers": {
    "github": {
      "env": {
        "GITHUB_TOKEN": "${WORK_GITHUB_TOKEN}",
        "DEBUG": null
      }
    },
    "internal-tools": {
      "url": "https://internal.company.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_TOKEN}"
      }
    }
  }
}

機能:

• 継承: 子設定は親の値を上書きします
• 複数の親: "extends": ["./base1.json", "./base2.json"]
• パス解決: ~、相対パス、絶対パスをサポート
• 環境変数の削除: null を使用して継承された環境変数を削除

戦略の選択

環境変数の展開

Claude Code互換の構文をサポート:

• ${VAR} - VARの値に展開 (未定義の場合はエラー)
• ${VAR:-default} - VARが未定義の場合はデフォルト値を使用

📋 コマンド

hatago init

対話式セットアップで設定ファイルを作成:

hatago init                    # 対話モード
hatago init --mode stdio       # STDIOモードの設定
hatago init --mode http        # HTTPモードの設定
hatago init --force            # 既存のファイルを上書き

hatago serve

MCPハブサーバーを起動:

hatago serve --stdio --config ./hatago.config.json  # STDIOモード (デフォルト、設定ファイルが必要)
hatago serve --http                                     # HTTPモード (設定はオプション)
hatago serve --config custom.json  # カスタム設定
hatago serve --verbose         # デバッグログを有効にする
hatago serve --tags dev,test   # タグでサーバーをフィルタリング
hatago serve --env-file ./.env # 起動前に.envファイルから変数を読み込む (複数指定可)
hatago serve --env-override    # --env-fileを使用する際に既存の環境変数を上書きする

ファイルからの環境変数の読み込み

--env-file <path...> を使用して、設定の解析前に変数を読み込みます。これにより、変数をグローバルにエクスポートすることなく ${VAR} および ${VAR:-default} のプレースホルダーを解決できます。

• 形式: KEY=VALUE、export KEY=VALUE、# コメント、空行。
• 引用符は削除されます; エスケープされた \n、\r、\t をサポートします。
• パス: カレントワーキングディレクトリに対する相対パス、~/ はホームディレクトリに展開されます。
• 優先順位: ファイルは指定された順序で適用されます; 既存の process.env キーは、--env-override が指定されていない限り保持されます。

✨ パフォーマンスの改善 (v0.0.14)

• 起動速度が8.44倍向上: 85.66ms → 10.14ms
• パッケージサイズが17%削減: 1.04MB → 854KB (181KBの削減)
• アーキテクチャの簡素化: EnhancedHubと管理レイヤーを削除
• トレードオフ: 組み込みの設定監視を削除 (代わりにnodemon/PM2を使用)

🔧 高度な使用法

プログラマティックAPI

import { startServer } from '@himorishige/hatago-mcp-hub';

// サーバーをプログラムで起動
await startServer({
  mode: 'stdio',
  config: './hatago.config.json',
  logLevel: 'info'
});

カスタムハブの作成

import { createHub } from '@himorishige/hatago-mcp-hub';

const hub = createHub({
  mcpServers: {
    memory: {
      command: 'npx',
      args: ['@modelcontextprotocol/server-memory']
    }
  }
});

// アプリケーションでハブを直接使用
const tools = await hub.listTools();

🏗️ アーキテクチャ

Client (Claude Code, etc.)
    ↓
Hatago Hub (Router + Registry)
    ↓
MCP Servers (Local, NPX, Remote)

サポートされるMCPサーバー

ローカルサーバー

• 任意の実行可能なMCPサーバー
• Python、Node.js、またはバイナリサーバー
• MCPプロトコルをサポートするカスタムスクリプト

NPXサーバー

• @modelcontextprotocol/server-filesystem
• @modelcontextprotocol/server-github
• @modelcontextprotocol/server-memory
• 任意のnpmで公開されたMCPサーバー

リモートサーバー

• DeepWiki MCP (https://mcp.deepwiki.com/sse)
• 任意のHTTPベースのMCPエンドポイント
• MCPプロトコルをサポートするカスタムAPIサーバー

🐛 トラブルシューティング

一般的な問題

1. "No onNotification handler set" 警告

   • StreamableHTTPトランスポートを使用したHTTPモードでは正常です
   • ハブが通知を適切に処理します

2. サーバー接続エラー

   • 環境変数が設定されていることを確認してください
   • リモートサーバーのURLにアクセスできることを確認してください
   • --verbose フラグを使用して詳細なログを表示してください

3. ツール名の衝突

   • Hatagoは自動的にサーバーIDをプレフィックスとして付けます
   • 元の名前はハブ内で保持されます

デバッグモード

# 詳細なログを有効にする
hatago serve --verbose

# サーバーのステータスを確認する
hatago status

🤝 コントリビューション

コントリビューションは大歓迎です！詳細については、GitHubリポジトリ をご覧ください。

📄 ライセンス

MITライセンス

🔗 リンク

• npmパッケージ
• GitHubリポジトリ
• MCPプロトコル仕様

🙏 クレジット

このプロジェクトは、Hono とAnthropicによる Model Context Protocol SDK を使用して構築されています。