hermai-mcp

Hermai MCP

Hermai 専用の Model Context Protocol サーバーです。

エージェントランタイムが MCP をサポートしており、Hermai をネイティブツールとして呼び出す場合にこのパッケージを使用してください。Hermai CLI は人間／オペレーター向けの別ツールであり、MCP には必要ありません。

インストール

npx で直接実行します。

npx -y hermai-mcp

または、グローバルにインストールします。

npm install -g hermai-mcp
hermai-mcp

MCP クライアントの設定

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

任意の環境変数：

• HERMAI_API_BASE または HERMAI_PLATFORM_URL：API のベース URL です。デフォルトは https://api.hermai.ai です。
• HERMAI_API_KEY または HERMAI_PLATFORM_KEY：認証が必要な Hermai API 用の API キーです。公開スキーマの検索とスキーマリクエストの送信にはキーは必要ありません。キーを設定すると、fetch_schema 実行ツールも使用できるようになります（下記参照）。
• HERMAI_FETCH_TIMEOUT_MS：fetch_schema のリクエストタイムアウトです。デフォルトは 120000 です（ホスト型のフェッチ処理には数十秒かかることがあります）。

Claude Code のワークフロー

スキーマを見つけ、利用可能なワークフローを調べ、認証済みの読み取りリクエストを実行する場合は、ローカル MCP サーバーを使用してください。Hermai MCP はローカルの stdio サーバーです。リモートの Claude コネクターではありません。

Claude Code をインストールしてから、個人用の Claude Code 設定に Hermai を追加します。

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

キーはローカルの Claude Code 設定に保存されます。このコマンドをリポジトリ、共有のシェル履歴、またはプロジェクトスコープの MCP 設定に記述しないでください。

Claude Code がサーバーを認識できることを確認します。

claude mcp list

次に Claude Code を起動し、次の 2 段階のリクエストを使用します。

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.

選択したワークフローを承認した後：

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 はキーなしで安全に使用できます。fetch_schema はキーが設定されている場合にのみ表示されます。これは Hermai Cloud 経由でデータを読み取り、リクエストが成功するとクレジットを消費します。サーバーにブラウザーの Cookie、Bearer トークン、または別のサービスのデータを変更するリクエストを渡さないでください。

完全な検証チェックリストと想定される失敗パターンについては、Claude Code ガイドを参照してください。

ツール

常に使用可能（キー不要）：

• lookup_schema — ドメイン、タスク、カテゴリ、または検証状態で Hermai スキーマを検索します。
• list_public_schemas — 公開スキーマをページ単位で取得します。
• submit_schema_request — 不安定なブラウザー／API ワークフローについて、6 項目の受付フォームを送信します。
• classify_browser_workflow — ワークフローが直接 API、隠れたエンドポイント、ブラウザーのみ、または所有者／認証対応のどれに該当するかをローカルで分類します。
• check_schema_request_status — スキーマリクエストのステータスを確認します。

HERMAI_API_KEY（または HERMAI_PLATFORM_KEY）が設定されている場合のみ使用可能：

• fetch_schema — 登録済みスキーマをホスト型の /v1/fetch 経由で実行し、ライブデータを返します。**読み取り専用のデータ取得であり、Hermai クレジットを消費します。標準的な呼び出しは 1 クレジット、一部の高コストなサイトは 5 クレジットです。課金対象となるのは成功した呼び出しのみです。**入力：site、endpoint（両方とも事前に lookup_schema で解決してください。endpoint は大文字と小文字を区別します）、および任意の params。結果には、上流の data に加えてメタ情報の概要（credits_used、credits_remaining、latency_ms、cached）が含まれます。エラーには API の code と message が表示され、クレジット不足を示す 402 レスポンスでアップグレード方法が提示される場合は、upgrade_to と upgrade_url も表示されます。読み取りワークフローにのみ使用してください。書き込みや所有者の承認が必要なワークフローにはこのツールではなく、Hermai CLI の署名付き書き込み機能を使用してください。

スキーマリクエストの送信を通じて、Cookie、Bearer トークン、API キー、セッション ID、またはプライベートなセッションデータを送信しないでください。