Skip to main content
Glama
darrenzwchan

Hermes MCP Server

by darrenzwchan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

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

Related MCP server: webdocs-mcp

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.

Available Tools

8 tools
hermes_check_authA

Check whether the Hermes session cookie is valid. Call this if other tools fail with an auth error.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool checks cookie validity, implying a boolean or success/failure response. While it does not detail the exact output format, the behavior is straightforward and the description is sufficient for a simple check tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of just two sentences, with the key action and usage context front-loaded. Every word is essential, with no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has zero parameters, no output schema, and a simple purpose, the description is complete. It provides all necessary context for an agent to understand when and why to invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so schema coverage is trivially 100%. The description adds no parameter information, but none is needed as the tool takes no inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the verb 'check' and specifies 'Hermes session cookie validity', clearly indicating what the tool does. It distinguishes itself from sibling tools like hermes_login and hermes_sharepoint_login, which are for obtaining authentication, not checking its validity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to call this tool: 'Call this if other tools fail with an auth error.' This provides clear guidance on the appropriate context, directing agents to use it as a diagnostic step.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hermes_get_documentA

Fetch a Hermes document by its ID (e.g. an objectID from a search result). Returns title, metadata, summary, and source links.

ParametersJSON Schema
NameRequiredDescriptionDefault
documentIdYesThe document objectID.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility. It discloses return fields (title, metadata, summary, source links) but does not specify auth requirements, error behavior, or whether the operation is read-only. Basic behavioral info is provided, but significant gaps remain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that efficiently conveys purpose and return. No unnecessary words. It is front-loaded with the action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description is largely complete. It specifies both how to use (by ID) and what is returned. Minor missing details like auth requirements could improve completeness but are not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the parameter with 100% description. The tool description adds value by explaining that the documentId is typically an objectID from search results, providing context beyond the schema's bare definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Fetch', the resource 'Hermes document', and the method 'by its ID'. It provides an example of where the ID comes from (objectID from search), which helps differentiate from sibling tools like hermes_get_document_content that fetch full content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context (after search) but does not explicitly state when to use this tool versus alternatives like hermes_get_document_content or hermes_get_related_resources. No when-not-to-use guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hermes_get_document_contentA

Read the FULL text of a Hermes document. By default (source=auto) it tries, in order: the Hermes search index (no SharePoint permissions), then your signed-in browser session over CDP, then a SharePoint/Graph fetch. Provide a documentId (preferred) or a webUrl directly.

ParametersJSON Schema
NameRequiredDescriptionDefault
indexNoWhich index holds the doc (default: docs).
sourceNoauto (default): index → browser → SharePoint. index: only the low-privilege search index. browser: only your signed-in Chrome session (no admin/scopes). sharepoint: force the Graph fetch.
webUrlNoA SharePoint document URL, if you already have it (used by the browser and SharePoint paths).
maxCharsNoTruncate the returned text to N characters (default 20000).
documentIdNoThe document objectID; used for the index lookup and to resolve the SharePoint webUrl.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose all behavioral traits. It explains the automatic fallback sequence, the limitations of the index source (no SharePoint permissions), and the browser source (requires signed-in session). It does not mention potential failures or output format, but the disclosure is thorough for the available information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: the first clearly states the purpose, the second covers all key behavioral and parameter guidance. No redundant words, perfectly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters, no output schema), the description is nearly complete. It covers fallback logic, parameter preferences, and default behaviors. Lacking only explicit error handling or return format, which is acceptable without an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the interplay between source, documentId, and webUrl, and the truncation behavior with maxChars, surpassing the schema's property descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Read the FULL text of a Hermes document,' a specific verb+resource combination that clearly states the tool's purpose. It distinguishes from siblings by emphasizing the full-text retrieval and multi-source fallback strategy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use each source mode (index, browser, sharepoint) and advises using documentId as preferred over webUrl. However, it does not explicitly state when not to use this tool or compare it to alternative tools like hermes_get_document.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hermes_loginA

Open a browser sign-in window for Hermes (SSO) and capture the session cookie. By default it WAITS until you finish signing in, then returns success so you can proceed. Call this at the start of a Hermes task if not signed in, or whenever a tool reports an authentication error. (Skips the popup if already signed in.)

ParametersJSON Schema
NameRequiredDescriptionDefault
waitNoWait until sign-in completes before returning (default: true).
timeoutSecondsNoMax seconds to wait for sign-in, 30-300 (default: 150).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses waiting behavior by default, popup skipping if already signed in, and session cookie capture. This adds meaningful context beyond the bare schema, though error handling details are omitted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no fluff. The first sentence states core purpose and capture action, the second highlights default behavioral trait, and the third provides usage context. Information is front-loaded and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description notes 'returns success so you can proceed'. It covers parameter usage, behavioral expectations, and use cases. While error handling and return format could be more explicit, the description is sufficiently complete for a login tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema: it mentions the 'wait' behavior inline but does not elaborate on 'timeoutSeconds'. The schema already documents both parameters adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Open a browser sign-in window for Hermes (SSO) and capture the session cookie', specifying the verb, resource, and action scope. It distinguishes from sibling tools like hermes_check_auth (auth verification) and hermes_sharepoint_login (different SSO).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given: 'Call this at the start of a Hermes task if not signed in, or whenever a tool reports an authentication error.' It also mentions automatic skip if already signed in. While it doesn't name alternative tools for checking auth status, the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hermes_recently_viewed_docsA

List the current user's recently viewed Hermes documents.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only says 'list' with no disclosure of ordering, limits, metadata vs. full content, or authentication requirements. The agent gets minimal behavioral context beyond the name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that conveys the verb and resource with no extraneous words. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description is incomplete. It fails to mention what the returned list contains (IDs, titles, content), any default ordering, or pagination. The agent lacks critical details for using the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters (100% schema coverage), so the description does not need to add param details. The description adds the core purpose, which is sufficient for this zero-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (list), the resource (recently viewed Hermes documents), and the scope (current user). It is specific and distinguishes itself from sibling tools like hermes_get_document (single document) and hermes_search (query-based).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving a list of recently viewed documents but provides no explicit when-to-use, when-not-to-use, or alternative suggestions. With multiple sibling tools, some guidance would be helpful, but the tool's purpose is straightforward.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hermes_sharepoint_loginA

Connect SharePoint / Microsoft Graph so full document content can be read. Opens the normal Microsoft browser sign-in (no code to type); after you sign in once, the server stores a token that auto-refreshes. Call this if hermes_get_document_content says it is not configured.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutSecondsNoMax seconds to wait for approval (default 150).

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses the interactive browser sign-in process and automatic token refresh, which is useful behavioral context. Since no annotations exist, description carries full burden, but it does not detail timeout behavior or potential failures beyond the sign-in step.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, first sentence states purpose, second gives usage instruction. No redundant information, front-loaded, and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, description covers purpose, usage trigger, and behavioral details (browser sign-in, token refresh). Minor missing aspects like return value or error handling, but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter (timeoutSeconds) is fully described in the schema (coverage 100%). The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool connects to SharePoint/Microsoft Graph to enable full document content reading. It distinguishes from sibling 'hermes_login' by specifying SharePoint-specific scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to call this if 'hermes_get_document_content' indicates it is not configured, giving a clear trigger condition. Lacks explicit when-not-to-use or alternative tools, but the guidance is effective.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv1.0.0
    • First observedhermes_check_auth
    • First observedhermes_get_document
    • First observedhermes_get_document_content
    • First observedhermes_get_related_resources
    • First observedhermes_login
    • First observedhermes_recently_viewed_docs
    • First observedhermes_search
    • First observedhermes_sharepoint_login
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 8 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: auth checking, document retrieval, full-text content, related resources, login, recently viewed, search, and SharePoint login. No overlapping functionalities.

Naming Consistency5/5

All tools follow the consistent pattern 'hermes_verb_noun' using snake_case, with descriptive verbs like check, get, login, search, and recently_viewed. No mix of conventions.

Tool Count5/5

8 tools is well-scoped for a document management server, covering authentication, search, retrieval, and related resources without being excessive or insufficient.

Completeness4/5

The tool surface covers core read operations (search, get, content, related, recent) and auth flows. Missing write operations but likely intentional for a consumption-oriented server.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • anydocs

    kiyeonjeon21
    A
    license
    A
    quality
    A
    maintenance
    Provides fast, token-efficient search over coding agent documentation (e.g., Claude Code, Cursor) using local SQLite FTS5 indexing, with tools for searching snippets, reading pages, and grepping markdown.
    5
    MIT

  • webdocs-mcp

    saianthireddy
    A
    license
    Not graded
    quality
    B
    maintenance
    Crawl documentation sites, index them with hybrid search, and expose them as MCP tools so LLM agents can search and retrieve current docs.
    MIT

  • project-lore-mcp

    tamas-fm
    A
    license
    Not graded
    quality
    A
    maintenance
    Routes coding agents to the most relevant project documentation (decisions, intent, constraints) with provenance and freshness, providing tools for task routing, knowledge search, and document context.
    28
    MIT