Hermes Agent Tools

English | 简体中文

Expose Hermes Agent tools to Claude Code via MCP (Model Context Protocol)

Turn your Hermes Agent into an MCP server so Claude Code can call its tools (browser automation, terminal, file read/write, vision, etc.) directly — no delegate_task overhead, just native MCP integration.

Architecture

Claude Code (MCP Client) ←→ hermes-mcp-server.py ←→ Hermes tools
                                (stdio)            (terminal, browser, etc.)

Without this: Claude Code has limited built-in tools and can't access Hermes capabilities.

With this: Claude Code gets 34 Hermes tools as first-class MCP tools.

What You Get

Category	Tools
Browser	browser_navigate, browser_snapshot, browser_click, browser_type, browser_scroll, browser_vision, browser_console, ...
Terminal	terminal, process
File	read_file, write_file, patch, search_files
Web	web_search, web_extract
Vision	vision_analyze
Skills	skills_list, skill_view, skill_manage
Code	execute_code, delegate_task
Memory	memory, session_search
Other	todo, clarify, cronjob, text_to_speech, homeassistant

Prerequisites

1. Hermes Agent installed at ~/.hermes/hermes-agent
2. MCP SDK for Python:

   cd ~/.hermes/hermes-agent
   uv pip install mcp --python .venv/bin/python3
   

3. Claude Code v2.x with MCP support

Quick Start

Step 1: Install the MCP server

# Clone the repo
git clone https://github.com/DHKun/hermes-mcp.git
cd hermes-mcp

# Or just copy the script anywhere
cp hermes-mcp-server.py ~/.hermes/
chmod +x hermes-mcp-server.py

Step 2: Connect to Claude Code

# Via CLI (easiest)
claude mcp add hermes -- python /path/to/hermes-mcp-server.py

# Verify it works
claude mcp list
# Should show: hermes → python ... hermes-mcp-server.py

Step 3: Use Hermes tools in Claude Code

Once connected, Claude Code can naturally call Hermes tools:

# Open a browser and navigate
Use browser_navigate to check https://github.com/trending

# Run terminal commands with full context
Use terminal to run git status and git diff

# Read/write files with Hermes path handling
Use read_file to look at src/app.py
Use patch to add error handling to src/app.py

# Search across codebase
Use search_files to find all uses of "async def"

# Delegate complex tasks back to Hermes Agent
Use delegate_task with goal="Research the architecture of this repo"

Claude Code will automatically see Hermes tools alongside its native tools — no special syntax needed.

Configuration

Option A: Via Claude Code CLI (easiest)

claude mcp add hermes -- python /path/to/hermes-mcp-server.py

Option B: Via settings.json (persistent)

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "hermes": {
      "command": "python",
      "args": ["/path/to/hermes-mcp-server.py"]
    }
  }
}

Option C: Per-project (team-shared)

Add to .claude/settings.json in your project:

{
  "mcpServers": {
    "hermes": {
      "command": "python",
      "args": ["/path/to/hermes-mcp-server.py"]
    }
  }
}

How It Works

1. The MCP server (hermes-mcp-server.py) imports Hermes's tool registry at startup
2. It registers all Hermes tools as MCP tools with their full schemas
3. When Claude Code calls a tool, the server forwards it to Hermes's handler
4. Results are JSON-serialized and returned via stdio

The server uses stdio transport — the most reliable for local subprocess communication:

• No port conflicts
• No network overhead
• Works in all environments (local, SSH, Docker)
• Natural for Claude Code's subprocess model

Security

• The server runs as a subprocess of Claude Code, inheriting its environment (ANTHROPIC_API_KEY, etc.)
• It does not expose Hermes's messaging adapters (Telegram, Discord)
• Large outputs are truncated at 200K chars (configurable via HERMES_MCP_MAX_OUTPUT)
• No credentials are leaked — only tool results are returned

Troubleshooting

"MCP server hermes failed to start"

Check the Python path — you must use the same Python that has the mcp package installed:

# Wrong (system Python may not have mcp)
python hermes-mcp-server.py

# Right (use Hermes's venv Python)
~/.hermes/hermes-agent/.venv/bin/python3 hermes-mcp-server.py

"Tool not found" errors

Claude Code may have cached old tool definitions. Restart the MCP server:

claude mcp remove hermes
claude mcp add hermes -- python /path/to/hermes-mcp-server.py

Very large outputs

Set HERMES_MCP_MAX_OUTPUT env var:

{
  "mcpServers": {
    "hermes": {
      "command": "python",
      "args": ["/path/to/hermes-mcp-server.py"],
      "env": { "HERMES_MCP_MAX_OUTPUT": "500000" }
    }
  }
}

Comparison with delegate_task

Aspect	delegate_task	hermes-mcp
Startup	Spawns new subprocess per task	One persistent server
Latency	~1-2s overhead per call	Near-zero (in-process)
Tool access	Via Hermes CLI parsing	Direct MCP calls
Best for	One-shot complex tasks	Fast, frequent tool calls
Session continuity	Each task is fresh	Server persists in session

For code writing/refactoring: hermes-mcp is faster.

For delegation to full agent with full context: delegate_task is still appropriate.

License

MIT