io.github.hermai-ai/hermai-mcp
Dedicated Hermai MCP server for schema lookup, request intake, and workflow classification.
Open source Open in the app JSON README (API)
About
Dedicated Hermai MCP server for schema lookup, request intake, and workflow classification.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- hermai-ai
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.0
- Open pull requests
- 1
- Last push
- 2026-08-13T17:16:28Z
- Repository state
- ativo
- Language
- JavaScript
- License
- NOASSERTION
- Added
- 2026-08-29 04:00:07
- Updated
- 2026-08-29 04:00:07
- Origin id
io.github.hermai-ai/hermai-mcp
README
# 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`:
```bash
npx -y hermai-mcp
```
Or install globally:
```bash
npm install -g hermai-mcp
hermai-mcp
```
## MCP Client Config
```json
{
"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:
```bash
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:
```bash
claude mcp list
```
Then start Claude Code and use this two step request:
```text
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:
```text
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](docs/claude-code.md).
## 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.