hermes-mcp: MCP tool for Hermes Agent

MCP server that lets Claude Desktop, Claude.ai, Codex and Cursor delegate tasks to a local Hermes Agent

What hermes-mcp does

hermes-mcp sits between an MCP client and the Hermes gateway. The client connects over HTTPS with OAuth 2.1 or a static bearer token, typically through a cloudflared tunnel to the server on localhost port 8765. The server, built on FastMCP with Streamable HTTP and PKCE, then calls the gateway's /v1/chat/completions endpoint on port 8642, the same agent loop that Telegram uses.

The idea is to use Claude or another client for daily chat and hand Hermes the work it is built for, such as scheduling cron jobs, browser automation, email, document creation, persistent skills and WhatsApp or Slack messaging. Configuration is through environment variables: OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_ISSUER_URL and HERMES_API_KEY are required, while HERMES_API_URL, HERMES_MODEL, MCP_ALLOWED_HOSTS, BIND_HOST and BIND_PORT are optional. A mint-client command generates OAuth credentials and a doctor command checks the setup. The README also covers a named tunnel and running as a systemd service.

Key features

OAuth 2.1 with PKCE or static bearer token access for MCP clients
Forwards tasks to the Hermes gateway's OpenAI-compatible API
mint-client command to generate OAuth credentials, and doctor to verify setup
Quick cloudflared tunnel for testing and a named tunnel for permanent use
systemd service instructions for running it continuously

When to use it

Asking Claude Desktop to hand a daily inbox summary to a Hermes cron job
Using Hermes browser automation and messaging from Cursor or Codex
Reaching a Hermes on a home server from Claude.ai on web or mobile

Who it is for: Hermes Agent users who run it on their own hardware and want to drive it from Claude, Codex or Cursor.

How it fits with Hermes Agent

Built for Hermes Agent: it talks to a running Hermes gateway and exposes it to external MCP clients.

How to install hermes-mcp

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

pipx install hermes-mcp
hermes-mcp mint-client
hermes-mcp doctor
hermes-mcp serve

Requirements: Hermes Agent installed and working on Linux or WSL with the gateway listening on 127.0.0.1:8642, a public HTTPS URL such as a cloudflared tunnel, and the OAuth and HERMES_API_KEY environment variables

FAQ

What is hermes-mcp?

hermes-mcp is an MCP server that lets Claude Desktop, Claude.ai, Codex, Cursor and other MCP clients delegate tasks to a local Hermes Agent. It talks to the Hermes gateway over its OpenAI-compatible API.

Does hermes-mcp work with Hermes Agent?

Yes, it is built for Hermes Agent. It assumes Hermes is already installed and working on Linux or WSL with the gateway listening on 127.0.0.1:8642.

How do I install hermes-mcp?

Install it with pipx install hermes-mcp, create OAuth credentials with hermes-mcp mint-client, check the setup with hermes-mcp doctor and start it with hermes-mcp serve. You also need a tunnel URL and the required environment variables.