hermes-mcp

An MCP server that turns internal Hermes documents (HashiCorp PRDs, RFCs, specs, memos) into agent tools — relevance search, document metadata, related resources, and full document bodies — plus a companion skill that makes your agent cross-check specs against the code in your editor.

Tools

hermes_search · hermes_get_document · hermes_get_document_content · hermes_get_related_resources · hermes_recently_viewed_docs · hermes_check_auth · hermes_login · hermes_sharepoint_login

Requirements

• Node.js 18+ (developed on 26)
• Google Chrome (for the sign-in / browser-content helpers)
• An MCP-capable agent (bob, Claude Desktop, VS Code, …)

Quick start

git clone https://github.com/yummydirtx/hermes-mcp.git
cd hermes-mcp
node install.js

The installer:

1. runs npm install,
2. copies the hermes skill into ~/.bob/skills/hermes/,
3. adds a hermes server to ~/.bob/settings/mcp.json (existing servers/secrets are preserved).

Then authenticate and reload your agent (below).

Claude Desktop or VS Code instead of bob? Run node install.js --claude, or copy a snippet from examples/.

Authenticate to Hermes

Hermes sits behind SSO. Capture your session one of two ways:

• Automatic (recommended):

  npm run attach
  

  A normal Chrome opens — sign in. Your session cookie is written to .hermes-cookie and hot-reloaded by the server. Keep that window open (it's also used for reading document bodies).

• Manual: in a logged-in Hermes tab, DevTools → Network → click a request → copy the Cookie: request header into .hermes-cookie:

  # macOS
  pbpaste > .hermes-cookie
  # Windows (PowerShell)
  Get-Clipboard | Set-Content -NoNewline .hermes-cookie
  

Verify with the hermes_check_auth tool.

Reading full document bodies

Bodies live in SharePoint. hermes_get_document_content tries, in order (source: "auto"):

1. Search index — the body Hermes already indexed. No extra permissions. Often enough.
2. Your browser session (source: "browser") — reads the file through the Chrome you signed into (npm run attach), over the DevTools protocol. No Microsoft Graph, no admin, no extra scopes — just the access you already have. Keep the document open in that Chrome.
3. Microsoft Graph (source: "sharepoint", via hermes_sharepoint_login) — needs Files.Read.All/Sites.Read.All. The built-in client can't obtain these in a locked-down tenant; use a dedicated Azure AD app (below).

Test the browser path directly:

npm run sp-browser "<sharepoint-document-url>"

Optional: dedicated Azure AD app (for the Graph path)

Azure Portal → App registrations → New registration → Redirect URI = Public client/native http://localhost → API permissions → Microsoft Graph → Delegated: Files.Read.All, Sites.Read.All, offline_access → Grant admin consent. Then set SP_CLIENT_ID and SP_TENANT_ID in the server env and run hermes_sharepoint_login.

Manual setup (no installer)

Add this to your agent's MCP config, fixing the path (see examples/ for bob / Claude / VS Code variants):

{
  "mcpServers": {
    "hermes": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/hermes-mcp/hermes-mcp.js"],
      "env": {
        "HERMES_BASE_URL": "https://hermes-sharepoint.hashicorp.services",
        "HERMES_COOKIE_FILE": "/ABSOLUTE/PATH/TO/hermes-mcp/.hermes-cookie"
      }
    }
  }
}

Then copy skills/hermes/SKILL.md into your agent's skills folder.

Windows notes

• Use PowerShell; node install.js works the same.
• npm run attach launches your installed Chrome/Edge. If it isn't found, set HERMES_CHROME to the browser's .exe.
• Absolute paths in args use backslashes — the installer writes them correctly; if editing by hand use \\ or forward slashes.

Configuration (env)

Var	Default	Purpose
HERMES_BASE_URL	https://hermes-sharepoint.hashicorp.services	Hermes host
HERMES_COOKIE_FILE	./.hermes-cookie	Session cookie (hot-reloaded)
HERMES_CDP_PORT	9222	Debug-Chrome port for attach + browser content
HERMES_CHROME	auto-detect	Path to Chrome/Edge executable
SP_CLIENT_ID, SP_TENANT_ID	–	Dedicated Azure AD app for the Graph path
SHAREPOINT_TOKEN_FILE	./.sharepoint-token	Optional pasted Graph token

Scripts

• npm start — run the server (stdio)
• npm run attach — capture the Hermes session from a real Chrome
• npm run sp-browser "<url>" — read a document via your browser session
• node install.js — set up + register with your agent

Security

Never commit .hermes-cookie, .sharepoint-*, or the browser profiles — they hold your live session. .gitignore already excludes them.