io.github.hermai-ai/hermai-mcp

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:

• HERMAI_API_BASE or HERMAI_PLATFORM_URL: API base URL. Defaults to https://api.hermai.ai.
• HERMAI_API_KEY or HERMAI_PLATFORM_KEY: 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).
• HERMAI_FETCH_TIMEOUT_MS: request timeout for fetch_schema. 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.

lookup_schema is safe to use without a key. fetch_schema 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.
• list_public_schemas — page through public schemas.
• submit_schema_request — submit the six-field intake for a brittle browser/API workflow.
• classify_browser_workflow — locally classify whether a workflow maps to direct API, hidden endpoint, browser-only, or owner/auth work.
• check_schema_request_status — check a schema request status.

Available only when HERMAI_API_KEY (or HERMAI_PLATFORM_KEY) is set:

• fetch_schema — 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 lookup_schema first; endpoint is case-sensitive), and optional params. The result includes the upstream data plus a meta summary (credits_used, credits_remaining, latency_ms, cached); failures surface the API code and message, plus upgrade_to 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.

Never submit cookies, bearer tokens, API keys, session IDs, or private session data through schema-request intake.