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단계 — 단일 저장소 루트에 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와 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, mcp_servers: YAML 확인.
도구가 나타나지 않음
증상: 설치는 됐지만 MCP를 호출하지 않음.
원인: enabled: false, 좁은 tools.include, OAuth 미완료. hermes mcp configure github 실행.
SSH 원격 OAuth
증상: 노트북 브라우저, 헤드리스 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: URL을 확인하세요.supports_parallel_tool_calls: true를 사용하세요. Git/DB 동시 쓰기는 피하세요.hermes update 후 hermes mcp install <name>을 다시 실행하고, 새 도구는 hermes mcp configure로 추가하세요.