# hermes-mcp-bridge

Model Context Protocol (MCP) server for [Hermes Agent](https://github.com/NousResearch/hermes-agent).

Connects MCP-compatible clients (Cursor, Claude Desktop, Antigravity, Windsurf) to local or remote Hermes instances.

## Features

- **Shell execution**: Run bash commands in the workspace (`exec_command`).
- **History & inspection**: Read conversation transcripts, tool outputs, and token counts from Hermes's SQLite database (`get_conversation`, `search_conversation`, `list_sessions`, `list_profiles`).
- **Run control**: Send messages, send slash commands, cancel active runs, and release stuck leases (`send_message`, `steer_agent`, `cancel_run`, `get_agent_status`, `clear_stuck_lease`, `restart_gateway`).
- **Git operations**: Check status, diffs, logs, commit changes, and switch branches (`git_status`, `git_diff`, `git_log`, `git_commit`, `git_checkout`).
- **File operations**: Read and write workspace files (`read_file`, `write_file`).

## Installation

Requires Python 3.10+.

```bash
git clone https://github.com/shakilapr/hermes-mcp-bridge.git
cd hermes-mcp-bridge
pip install .
```

For development:

```bash
pip install -e ".[dev]"
```

## Configuration

Configure using environment variables:

| Variable | Default | Description |
| :--- | :--- | :--- |
| `HERMES_HOME` | `~/.hermes` | Path to Hermes home directory (contains `state.db` and profiles). |
| `HERMES_API_URL` | `http://127.0.0.1:8642` | Hermes gateway URL. |
| `HERMES_API_KEY` | None | Optional API key for gateway requests. |
| `HERMES_PROFILE` | `default` | Default Hermes profile to use. |
| `HERMES_SSH_HOST` | None | Remote SSH host alias or IP. If set, queries and commands run over SSH. |
| `HERMES_SSH_PORT` | `22` | SSH port. |
| `HERMES_SSH_KEY` | None | Path to SSH private key. |
| `HERMES_REMOTE_HOME` | `/root/.hermes` | Path to Hermes home directory on remote server. |
| `HERMES_ALLOWED_WORKSPACES` | `*` | Comma-separated list of allowed workspace paths. |

## MCP Client Configuration

### Local Hermes

Add to your MCP client configuration (`claude_desktop_config.json`, Cursor MCP settings, etc.):

```json
{
  "mcpServers": {
    "hermes": {
      "command": "hermes-mcp",
      "env": {
        "HERMES_HOME": "/path/to/.hermes"
      }
    }
  }
}
```

### Remote Hermes (over SSH)

Runs locally and connects to Hermes on a remote server through SSH. No bridge installation required on the server.

```json
{
  "mcpServers": {
    "hermes": {
      "command": "hermes-mcp",
      "env": {
        "HERMES_SSH_HOST": "user@your-server-ip",
        "HERMES_SSH_KEY": "/path/to/id_ed25519",
        "HERMES_REMOTE_HOME": "/root/.hermes"
      }
    }
  }
}
```

## Running the Server Directly

Stdio mode (default for MCP):

```bash
hermes-mcp
```

SSE mode (HTTP server):

```bash
hermes-mcp --transport sse --port 8000
```

## Testing

```bash
pytest
```

## License

MIT