トラブルシューティング

Hatago MCP Hubを使用中に発生する可能性がある問題と、その解決方法をまとめています。

🔝 よくある問題Top10

最も頻繁に報告される問題から確認してください

🔍 症状から探す

エラーメッセージや症状から問題を特定

よくある問題 Top 10

1. サーバーが起動しない

症状: hatago serveを実行してもサーバーが起動しない

考えられる原因

Node.jsのバージョンが古い
設定ファイルが見つからない
設定ファイルの構文エラー

解決方法

Node.jsバージョンを確認

node --version
# v20.0.0以上が必要

古い場合は更新：

# nvmを使用している場合
nvm install 20
nvm use 20

設定ファイルの存在確認
Terminal window
```
ls -la hatago.config.json
```
ない場合は作成：
Terminal window
```
npx @himorishige/hatago-mcp-hub init
```
設定ファイルの検証
Terminal window
```
# JSONの構文チェック
cat hatago.config.json | jq .
```
エラーが表示される場合は構文を修正

再発防止

Node.jsのバージョン管理に.nvmrcを使用
設定ファイルをGitで管理
VS Codeの拡張機能でJSON検証を有効化

2. 環境変数が展開されない

症状: ${GITHUB_TOKEN}などの環境変数がエラーになる

考えられる原因

環境変数が設定されていない
シェルの設定ファイルに記載されていない
Claude Codeが環境変数を読み込めていない

解決方法

環境変数の確認
Terminal window
```
echo $GITHUB_TOKEN
```

環境変数の設定

# 一時的に設定
export GITHUB_TOKEN="your-token-here"

# 永続的に設定（~/.zshrc または ~/.bashrc）
echo 'export GITHUB_TOKEN="your-token-here"' >> ~/.zshrc
source ~/.zshrc

デフォルト値を使用

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN:-default-value}"
  }
}

再発防止

.env.exampleファイルで必要な環境変数を文書化
デフォルト値を設定して開発を容易に

3. Claude Codeでツールが表示されない

症状: Claude Codeで/toolsを実行してもHatagoのツールが出ない

考えられる原因

.mcp.jsonが正しく設定されていない
Claude Codeが再起動されていない
Hatagoサーバーが起動に失敗している

解決方法

.mcp.jsonの確認

cat .mcp.json

正しい設定例：

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

Claude Codeの再起動
- VS Codeメニュー → 「Developer: Reload Window」
- または Cmd+R (Mac) / Ctrl+R (Windows/Linux)
ログの確認
- VS Code出力パネル → 「MCP」チャンネルを選択
- エラーメッセージを確認

再発防止

.mcp.jsonをプロジェクトテンプレートに含める
READMEに再起動手順を明記

4. ツール名が重複している

症状: Tool 'read_file' already existsのようなエラー

考えられる原因

複数のMCPサーバーが同じツール名を提供
Hatagoの自動プレフィックス機能が無効

解決方法

Hatagoは自動的にサーバーIDをプレフィックスとして追加します：

{
  "mcpServers": {
    "fs1": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./dir1"]
    },
    "fs2": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./dir2"]
    }
  }
}

ツールは以下のように区別されます：

fs1_read_file
fs2_read_file

再発防止

サーバーIDを明確に命名
同じタイプのサーバーには番号や用途を付ける

5. リモートサーバーに接続できない

症状: HTTPまたはSSEサーバーへの接続がタイムアウト

考えられる原因

ネットワーク接続の問題
URLが間違っている
認証情報が不正
CORSの問題

解決方法

URLの確認

# curlでテスト
curl -I https://api.example.com/mcp

認証ヘッダーの設定

{
  "mcpServers": {
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

タイムアウトの延長
```
{
  "timeout": 30000 // 30秒
}
```

再発防止

ヘルスチェックエンドポイントを用意
接続テストスクリプトを提供

6. メモリ不足エラー

症状: JavaScript heap out of memoryエラー

考えられる原因

大量のMCPサーバーを同時起動
メモリリークのあるサーバー
Node.jsのメモリ制限

解決方法

Node.jsのメモリ制限を増やす

NODE_OPTIONS="--max-old-space-size=4096" npx @himorishige/hatago-mcp-hub serve

不要なサーバーを無効化

{
  "mcpServers": {
    "heavy-server": {
      "disabled": true,
      "command": "..."
    }
  }
}

タグを使って必要なサーバーのみ起動
Terminal window
```
hatago serve --tags essential
```

再発防止

メモリ使用量の監視
開発と本番でサーバー構成を分ける

7. 設定の変更が反映されない

症状: hatago.config.jsonを変更しても動作が変わらない

考えられる原因

ホットリロードが無効
キャッシュの問題
設定ファイルのパスが異なる

解決方法

ホットリロードを有効化
Terminal window
```
hatago serve --watch
```
手動で反映 変更を即時反映したい場合は --watch を有効化して起動し、または一度再起動します。

サーバーを再起動

# Ctrl+C で停止してから
hatago serve

再発防止

--watchフラグをデフォルトで使用
package.jsonのスクリプトに追加

8. ポートが使用中

症状: Error: listen EADDRINUSE: address already in use

考えられる原因

前回のプロセスが終了していない
他のアプリケーションが同じポートを使用

解決方法

使用中のプロセスを確認

lsof -i :3535  # Mac/Linux
netstat -ano | findstr :3535  # Windows

プロセスを終了

kill -9 <PID>  # Mac/Linux
taskkill /PID <PID> /F  # Windows

別のポートを使用
Terminal window
```
hatago serve --http --port 3536
```

再発防止

グレースフルシャットダウンの実装
ポート番号を設定ファイルで管理

9. パフォーマンスが遅い

症状: ツールの実行が遅い、レスポンスが返ってこない

考えられる原因

多数のサーバーが同時に起動
ネットワーク遅延
サーバー側の処理が重い

解決方法

必要最小限のサーバーのみ起動
Terminal window
```
# タグで絞り込み
hatago serve --tags essential
```
状態を確認

内部リソース hatago://servers を読み取り、接続状態を確認します。
タイムアウトを調整
```
{
  "timeout": 60000 // 60秒に延長
}
```

再発防止

サーバーの遅延ロード実装
キャッシュの活用
非同期処理の最適化

10. ログが出力されない

症状: デバッグ情報が表示されない

考えられる原因

ログレベルが高すぎる
出力先が異なる
サイレントモード

解決方法

ログレベルを下げる

hatago serve --verbose
# または
hatago serve --log-level debug

設定ファイルで指定
```
{
  "logLevel": "debug"
}
```
VS Code出力パネルを確認
- 出力 → MCPチャンネルを選択

再発防止

開発時は常に--verboseを使用
ログファイルへの出力オプション追加

🔍 症状から問題を探す

起動時のエラー

Command not found - Module not found - Invalid configuration

接続エラー

Connection refused - Timeout - Authentication failed

実行時エラー

Tool not found - Permission denied - Out of memory

パフォーマンス問題

レスポンスが遅い - CPU使用率が高い - メモリリーク

💡 デバッグのヒント

詳細なログを確認したい場合は、以下のコマンドでデバッグモードを有効にできます：

# 環境変数で設定
DEBUG=* hatago serve --verbose

# 設定ファイルで指定
{
  "logLevel": "debug"
}

📚 さらなるサポート

問題が解決しない場合は：

GitHub Issuesで既存の問題を検索
新しいIssueを作成（エラーログを含めてください）
Discussionsで質問