How to Connect Claude Desktop to Hermes Agent with MCP

Claude Desktop can talk to external tools through Model Context Protocol. Hermes Agent can expose an MCP server. Put those together and Claude Desktop can reach a Hermes-powered tool layer instead of staying inside a pure chat window. The setup is powerful, but it should be treated as a local tool bridge, not a harmless plugin toggle.

When this connector makes sense#

Use the Claude Desktop MCP connector when the user experience you want is still Claude Desktop, but the missing piece is access to Hermes workflows. Good fits include:

• A local Claude Desktop session that needs a Hermes skill, file workflow, or project convention.
• A demo where Claude Desktop calls into the same agent runtime you use from terminal or Telegram.
• A controlled personal setup where the MCP server only exposes tools you trust.
• A migration path for users who like Claude Desktop but want Hermes memory, profiles, cron, or gateway workflows later.

Do not use this connector as a shortcut around permissions. If an MCP server can access a directory, account, browser profile, or API token, Claude Desktop can indirectly ask for actions against that resource. That is why profile boundaries from the Hermes Agent profiles guide matter before you connect anything with credentials.

Prerequisites#

Before opening Claude Desktop, prove the Hermes side works by itself:

1. Install Hermes using the Hermes Agent setup guide or the shorter install checklist.
2. Configure one model provider with hermes model or hermes setup.
3. Run hermes doctor and fix missing dependencies.
4. Run a terminal smoke test such as hermes chat -q "say ready".
5. Decide which Hermes profile Claude Desktop should use.

If the setup fails before MCP is involved, use the Hermes troubleshooting guide. MCP should be the last layer you add, not the first thing you debug.

Step 1: start Hermes as an MCP server#

Hermes includes an MCP server mode:

hermes mcp serve

For a dedicated Claude Desktop profile, start it with that profile selected:

hermes --profile claude-desktop mcp serve

A dedicated profile keeps Claude Desktop's available tools, memory, sessions, and secrets separate from your main Telegram bot, Discord bot, or production automation. If you have not created one yet, the pattern is:

hermes profile create claude-desktop
hermes --profile claude-desktop setup
hermes --profile claude-desktop doctor

The exact transport and command wrapper can change as Claude Desktop evolves, but the principle is stable: Claude Desktop should launch or connect to a command that starts the Hermes MCP server for the intended profile.

Step 2: add the server to Claude Desktop#

Claude Desktop MCP servers are configured in its desktop configuration file. Add a server entry whose command runs Hermes in MCP server mode. Keep it boring and explicit: use a full path to the Hermes binary if Claude Desktop cannot find hermes from its reduced desktop app environment.

A typical shape looks like this:

{
  "mcpServers": {
    "hermes-agent": {
      "command": "hermes",
      "args": ["--profile", "claude-desktop", "mcp", "serve"]
    }
  }
}

If Claude Desktop launches with a reduced PATH on macOS, replace "hermes" with the absolute path from:

which hermes

Then restart Claude Desktop. If the server does not appear, test the same command in Terminal first. Desktop app environment problems are common; they are not proof that Hermes MCP is broken.

Step 3: expose a narrow tool surface first#

The safest first test is a harmless read-only workflow. Avoid starting with shell commands, browser profiles, email, cloud admin APIs, or write-enabled SaaS tools.

A good first pass is:

• One profile.
• One non-production working directory.
• One or two low-risk tools.
• No broad secret dump in the profile environment.
• No unattended write actions until you have verified prompts and logs.

If you need broad integrations, read MCP security risks for AI agents before adding them. MCP is convenient because it standardizes tool calling; it is risky for the same reason.

Step 4: test the connector like an operator#

After Claude Desktop sees the Hermes server, run a short staged test:

1. Ask Claude Desktop to list the Hermes MCP tools it can see.
2. Call a read-only tool or ask a harmless Hermes question.
3. Confirm the Hermes terminal logs show the expected request.
4. Try one scoped file or project task in a disposable directory.
5. Only then add stronger tools or credentials.

If the connector works in Claude Desktop but real Hermes tasks fail, debug the Hermes layer. If Hermes works in Terminal but Claude Desktop cannot see it, debug the desktop MCP config, PATH, and restart behavior.

Claude Desktop connector vs full Hermes gateway#

Claude Desktop is a good front-end for interactive desktop use. Hermes gateways are better when the agent needs to live where you already work: Telegram, Discord, Slack, webhooks, cron, or a VPS. That distinction matters.

Choose the Claude Desktop connector when:

• You want Claude Desktop as the interface.
• You are testing MCP or demoing a Hermes bridge.
• You only need interactive local work.

Choose the Hermes gateway path when:

• You want Telegram or Discord access.
• You need scheduled jobs and alerts.
• You need always-on uptime.
• You want a production-ish profile with logs, restart behavior, and provider controls.

For gateway work, start with Telegram setup, Discord setup, or the gateway troubleshooting guide.

The security rule#

Treat Claude Desktop plus Hermes MCP as one combined agent surface. Anything the Hermes profile can reach may become reachable through Claude Desktop prompts. Keep the profile narrow, keep secrets scoped, and use the smallest toolset that proves the workflow.

That is also the commercial decision point. If the value is the outcome rather than operating an MCP bridge, a hosted setup can be cheaper than debugging desktop launch paths, provider credits, and local gateway reliability. Compare FlyHermes when the work needs uptime more than tinkering.