Hermes Agent MCP Mac：開発ツールチェーン連携（2026）
Hermes Agent は MIT エージェント で、MCP により外部ツール（filesystem、GitHub、Codex）を ~/.hermes/config.yaml から接続できます。
なぜ Hermes に MCP
開発者には、限定されたファイルシステム、Issue/PR ツール、IDE 連携が同時に必要です。
クライアントは mcp_servers、サーバーは hermes mcp serve です。
Mac セットアップを先に完了してください。
アーキテクチャ
| Component | Path | Role |
|---|---|---|
| config | ~/.hermes/config.yaml | MCP servers |
| secrets | ~/.hermes/.env | keys |
| catalog | hermes mcp | install |
macOS で MCP を設定する 7 ステップ
ステップ 1 — MCP 依存関係の確認
標準の install.sh に MCP が含まれます。hermes doctor が警告する場合：
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
node --version と npx --version を確認してください。
ステップ 2 — リポジトリ 1 つに filesystem サーバー
~/.hermes/config.yaml の mcp_servers.project_fs に、実際のプロジェクトパスを指定します：
npx -y @modelcontextprotocol/server-filesystem /Users/you/dev/my-app（$HOME 全体はマウントしない）。
ステップ 3 — catalog から GitHub をインストール
hermes mcp または hermes mcp install github を実行。トークンは ~/.hermes/.env に保存され、ツールチェックリストで破壊的操作をオフにできます。
ステップ 4 — 任意: Codex CLI プリセット
codex が PATH にある場合: hermes mcp add codex --preset codex（stdio で codex mcp-server 相当）。
ステップ 5 — 機密ツールのホワイトリスト
各サーバーで tools.include（例: list_issues, search_code）と tools.prompts: false を設定し、必要な mcp_github_* だけを登録します。
ステップ 6 — TUI で検証
hermes を起動し、プロジェクトルートのファイル一覧を依頼。YAML 変更後は /reload-mcp。OAuth は新しいターミナルで hermes mcp login <server>（セッション内リロードは 30 秒でタイムアウト）。
ステップ 7 — Cursor に Hermes を公開
クライアント MCP 設定に "command": "hermes", "args": ["mcp", "serve"] を追加。読み取りは gateway 不要；送信は hermes gateway が必要 — Mac セットアップを参照。
開発レシピ
| Case | Transport | Config |
|---|---|---|
| repo | stdio | filesystem path |
| GitHub | stdio | catalog + .env |
| Codex | preset | --preset codex |
stdio vs HTTP — laptop: filesystem + one catalog first; Mac mini 24/7: limit stdio processes.
トラブルシューティング
MCP サーバーに接続できない
症状: 接続エラー、TUI に mcp_* ツールがない。
対処: uv pip install -e ".[mcp]" の後 hermes doctor。YAML の mcp_servers: を確認。
ツールが表示されない
症状: インストール成功後も MCP を呼ばない。
原因: enabled: false、狭い tools.include、OAuth 未完了。オンライン後 hermes mcp configure github。
SSH 先での OAuth
症状: ノート PC のブラウザ、ヘッドレス Mac 上の Hermes。
対処: リダイレクト URL を貼り付け、または ssh -L。対話 SSH で hermes mcp login。
FAQ
hermes mcp serve サーバーを持ち、Cursor と併用できます。リポジトリ操作は mcp_servers、IDE 連携は Cursor 側 MCP でも構いません。mcp_<server>_<tool> 形式で登録されます（ドットはアンダースコア）。自然言語でタスクを書けばモデルが選択します。optional-mcps/ は PR 審査済みですが、インストールは upstream の bootstrap を実行します。本番前に manifest の source: を確認してください。supports_parallel_tool_calls: true を有効化してください。同一リソースへの並列書き込みは避けます。hermes update 後に hermes mcp install <name> を再実行し、新ツールは hermes mcp configure で追加します。