Hermai MCP server

Hermai MCP

Dedicated Model Context Protocol server for Hermai.

Use this package when an agent runtime supports MCP and should call Hermai as native tools. The Hermai CLI is a separate human/operator tool and is not required for MCP.

Install

Run directly with npx:

npx -y hermai-mcp

Or install globally:

npm install -g hermai-mcp
hermai-mcp

MCP Client Config

{
  "mcpServers": {
    "hermai": {
      "command": "npx",
      "args": ["-y", "hermai-mcp"]
    }
  }
}

Optional environment variables:

• HERMAIAPIBASE or HERMAIPLATFORMURL: API base URL. Defaults to https://api.hermai.ai.
• HERMAIAPIKEY or HERMAIPLATFORMKEY: API key for authenticated Hermai APIs. Public schema lookup and schema-request intake work without a key. Setting a key also unlocks the fetch_schema execution tool (see below).
• HERMAIFETCHTIMEOUTMS: request timeout for fetchschema. Defaults to 120000 (hosted fetch lanes can run tens of seconds).

Claude Code workflow

Use the local MCP server when you want Claude Code to discover a schema, inspect the available workflow, and make an authenticated read request. Hermai MCP is a local stdio server. It is not a remote Claude connector.

Install Claude Code, then add Hermai to your personal Claude Code configuration:

export HERMAI_API_KEY='hm_sk_...'
claude mcp add --scope user hermai -e HERMAI_API_KEY="$HERMAI_API_KEY" -- npx -y hermai-mcp
unset HERMAI_API_KEY

The key is saved in your local Claude Code configuration. Do not put this command in a repository, shared shell history, or a project scoped MCP configuration.

Confirm that Claude Code can see the server:

claude mcp list

Then start Claude Code and use this two step request:

Use lookup_schema to find a verified public Hermai schema for [the source and task].
Before making a fetch, show me the site, endpoint, required parameters, and whether
the result can be retrieved with fetch_schema.

After you approve the selected workflow:

Use fetch_schema with the site, endpoint, and parameters we selected. Return a short
summary of the records, then show credits_used, credits_remaining, and cached from
the response metadata.

lookupschema is safe to use without a key. fetchschema appears only when the key is configured. It reads data through Hermai Cloud and consumes credits for a successful request. Do not give the server browser cookies, bearer tokens, or a request that changes data on another service.

For a full verification checklist and the expected failure paths, see the Claude Code guide.

Tools

Always available (no key required):

• lookup_schema — search Hermai schemas by domain, task, category, or verification state.
• listpublicschemas — page through public schemas.
• submitschemarequest — submit the six-field intake for a brittle browser/API workflow.
• classifybrowserworkflow — locally classify whether a workflow maps to direct API, hidden endpoint, browser-only, or owner/auth work.
• checkschemarequest_status — check a schema request status.

Available only when HERMAIAPIKEY (or HERMAIPLATFORMKEY) is set:

• fetchschema — execute a registered schema through hosted /v1/fetch and return live data. Read-only data retrieval, and it consumes Hermai credits: a standard call costs 1 credit and some higher cost sites cost 5; only successful calls are billed. Inputs: site, endpoint (resolve both with lookupschema first; endpoint is case-sensitive), and optional params. The result includes the upstream data plus a meta summary (creditsused, creditsremaining, latencyms, cached); failures surface the API code and message, plus upgradeto and upgrade_url when a credit 402 offers an upgrade path. Use it for read workflows only — write/owner-approved workflows go through the Hermai CLI's signed-write path, not this tool.

Shortened. The full README is on GitHub.