Hub-Equity MCP

hub-equity-mcp

LLM エージェント向けの標準化された XBRL 財務データ。 Claude Desktop、Cursor、および MCP 対応のあらゆるクライアントに、米国 SEC（EDGAR）と欧州 ESEF の提出書類から正規化された財務事実を提供する Model Context Protocol（MCP）サーバーです。

Hub-Equity は、米国 SEC のデータに加えて欧州 ESEFの提出書類も、統一されたハブ概念の語彙を通じて提供します。これにより、エージェントは REVENUE や TOTAL_ASSETS を指定するだけで、発行体が SEC に提出している場合でも ESEF に提出している場合でも、比較可能で出典にリンクされた値を取得できます。

成熟度。 このコネクターが利用する公開 REST API は本番環境で稼働しており、Hub-Equity 独自のチャットを支えています。このパッケージはセマンティックバージョニングに従っており、導入実績がまだ少ないため、ベータ分類を維持しています。

理由

• 2 つの制度を横断する単一の語彙。 SEC の us-gaap と ESEF の ifrs-full の概念は、標準化されたハブコードの単一セットにマッピングされるため、発行体やタクソノミーをまたいだ比較をすぐに行えます。
• すべての数値に出典が付いています。 財務事実には提出書類、期間、来歴が含まれるため、エージェントは推測ではなく引用できます。
• 修正再表示に対応。 明示的な修正と、修正提出書類のないまま後続の提出書類で数値が異なる形で再掲される暗黙的な修正再表示を検出し、各変更をその変更をもたらした提出書類と結び付けます。
• 読み取り専用かつ閉世界です。 すべてのツールが MCP 仕様に従って readOnlyHint=true、idempotentHint=true、destructiveHint=false、openWorldHint=false を宣言するため、クライアントは内部を調査せずに安全性やキャッシュについて判断できます。
• データベースの認証情報は不要です。 公開パッケージは HTTPS 経由で公開 REST API（https://api.hub-equity.com）にのみ接続します。データベースキーを同梱したり、要求したりすることはありません。

インストール

pipx run hub-equity-mcp

pipx run（または uvx hub-equity-mcp）は、分離された環境でサーバーを取得して起動します。pip install hub-equity-mcp も使用できます。Python 3.12 以降が必要です。

認証とアクセス

サーバーは hubq_ キー（環境変数 HUBEQUITY_API_KEY）が必要な公開 REST API にのみ接続します。

• 無料キー。 https://hub-equity.com/settings/api-keys でアカウントとキーを 1 分で作成できます。基本ツール一式（エンティティ検索、正規化された財務事実、時系列、セグメント、スクリーナー、データ品質評価、FX 換算など）を利用できます。
• 有料プラン。 プレミアムツール（修正再表示の差分、計算ツリー、期間横断比較、発行体横断比較、検証チェック、拡張概念）が利用可能になり、レート制限も引き上げられます。以下の表をご覧ください。

公開パッケージがデータベースに直接接続することはなく、REST API のみに接続します。

クライアントの設定

Claude Desktop

claude_desktop_config.json に追加します （macOS：~/Library/Application Support/Claude/claude_desktop_config.json、 Windows：%APPDATA%\Claude\claude_desktop_config.json）。

{
  "mcpServers": {
    "hub-equity": {
      "command": "pipx",
      "args": ["run", "hub-equity-mcp"],
      "env": {
        "HUBEQUITY_API_KEY": "INSERT_YOUR_API_KEY"
      }
    }
  }
}

HUBEQUITY_API_KEY が設定されていない場合、すべてのツール呼び出しは、無料キーへのリンクとともに HUBEQUITY_API_KEY is not set を返します。

Cursor

プロジェクトのルートにある .cursor/mcp.json または Cursor のグローバル MCP 設定に追加します。

{
  "mcpServers": {
    "hub-equity": {
      "command": "pipx",
      "args": ["run", "hub-equity-mcp"],
      "env": {
        "HUBEQUITY_API_KEY": "INSERT_YOUR_API_KEY"
      }
    }
  }
}

環境変数

• HUBEQUITY_API_KEY（必須）：hubq_ キーです。無料キーでは基本ツールを利用でき、有料プランではプレミアムツールと引き上げられたレート制限を利用できます。
• HUBEQUITY_API_URL（任意）：デフォルトは https://api.hub-equity.com です。キーが設定されている場合は https:// が必須です（サーバーは、ループバック以外のホストに平文で Bearer キーを送信しません）。

機能

種類	内容
ツール	読み取り専用ツール：検索、財務事実、時系列、セグメント、フォレンジックチェック（以下の表）
リソース	ハブカタログ、財務諸表スキーマ、プランカタログ、利用ガイド、カバレッジスナップショット
プロンプト	分析テンプレート（以下に一覧）
補完 API	{hub_code} のオートコンプリート

ツール

機械可読なティアカタログは、リソース （hub-equity://catalog/tool-tiers）として提供されます。Free ツールでは検索と識別を利用できます。 すべての有料プラン（Builder、Team、Enterprise）で利用できる Pro ツールでは、フォレンジック分析の詳細情報（計算ツリー、修正や非公表の修正に関する修正差分、期間横断の比較、発行体横断の比較、検証結果、拡張コンセプト）を利用できます。ツールのティアは、呼び出す REST エンドポイントのティアと一致します。すべての Pro ツールのエンドポイントでは、サーバー側で facts.premium スコープが必要です。また、Free の上限（get_fact_decomposition はロールアップコンポーネントやディメンションスライスなしで深さ 1 まで、screen_companies は品質フィルターなしで最大 20 件、get_segments はメンバーなしで軸のみ、roll_up_metric はルールなしで値のみ）は、このパッケージだけでなく API によって適用されます。

ツール	プラン	内容
find_entity(query)	無料	名前、ティッカー、CIK で検索します。他のツールで必要となる entity_id を返します。
get_fact(entity_id, hub_concept_code, fiscal_year, fiscal_period_type?)	無料	正規化された値と、その出典となる提出書類を返します。
get_fact_decomposition(entity_id, fiscal_year, hub_concept_code? or qname?, depth?)	無料（深度 1、リンクベースのみ）／Pro（深度 2～3）	ハブの集計値、XBRL 計算リンクベースの子項目、ディメンション別の内訳を返します。無料プランでは、ロールアップの構成要素とディメンション別のスライスを除くリンクベース層を利用できます。
search_concept(query)	無料	ラベルまたはコードの一部からハブコードを特定します。
list_hubs(category?, include_non_primary?, limit?)	無料	カテゴリ別に標準化されたハブのカタログを一覧表示します。
get_entity_profile(entity_id)	無料	セクター、監査人、従業員数、会計年度末、最近の提出書類を返します。
get_metric_history(entity_id, hub_concept_code, n_years?)	無料	前年比成長率と CAGR を含む、N 年分の時系列データを返します。
get_segments(entity_id, hub_concept_code, fiscal_year)	無料（上限あり）	ディメンションの軸／メンバー別内訳（セグメント、地域）を返します。無料プランではメンバーを除く軸を利用でき、Pro ではすべてのメンバーを利用できます。
get_amendments(entity_id, fiscal_year?)	無料	10-K/A による修正再表示の概要を返します。すべての修正と、修正ごとの概念別変更（修正あたり 50 件）を確認できます。
get_silent_restatements(entity_id, fiscal_year?)	無料	サイレント修正再表示を返します。修正書類の提出なしに、後の提出書類の比較列で異なる値が再掲されたケースを、その修正を明らかにした提出書類ごとにグループ化します（提出書類あたり 50 件の変更）。
compare_entities(entity_ids, hub_concept_codes, fiscal_year)	Pro（最大 10×10）	1 つの期間について、暦年を揃えた発行体間の比較マトリックスを返します。UUID、ティッカー、または TICKER.MIC を指定できます。
roll_up_metric(entity_id, hub_concept_code, fiscal_year)	無料（上限あり）	値が直接タグ付けされていない場合に、符号付きの子項目から値を計算します。無料プランでは値を、Pro では計算ルールと、その根拠となる符号付きの寄与値を確認できます。
convert_currency(amount, from_currency, to_currency, date?, rate_type?)	無料	ECB 基準為替レート（終値、年初来平均、前年平均）による通貨換算を行います。
screen_companies(country?, sector?, min_revenue?, ..., sort_by?, limit?)	無料（上限 20 件、品質フィルターなし）／Pro（上限数がより多い）	メタデータ、収益、監査、データ品質で発行体の全体を絞り込みます。
get_amendment_diff(entity_id, fiscal_year?, hub_concept_code?, min_diff_pct?, kind_filter?)	Pro	10-K/A の概念別差分を返します。重要度、種類、概念でフィルタリングでき、ラベル、絶対差、両方の提出書類を出典として確認できます。
get_silent_restatement_diff(entity_id, fiscal_year?, hub_concept_code?, min_diff_pct?, kind_filter?)	Pro	サイレント修正再表示について、同じ差分情報を返します。
get_calculation_tree(filing_id, link_role?)	Pro	提出書類の計算リンクベースを返します。すべての合計項目と構成要素について、宣言された符号と、提出された値が示す符号を並べて確認できます。
compare_filings(entity_id, fiscal_year_a, fiscal_year_b, hub_concept_codes?)	Pro	同一発行体の期間をまたいだ比較を行い、新規／削除／符号反転／修正再表示のフラグを返します。
get_extension_concepts(entity_id, status_filter?, limit?)	Pro	標準タクソノミー外で宣言された発行体固有の qname を返します。
get_data_quality_grade(entity_id)	無料	A+～D の評価（または評価なし）、評価を左右する 2 つの判定基準と件数、データの鮮度、直接値と導出値の内訳を返します。
get_validation_results(filing_id?, entity_id?, fiscal_year?, status_filter?)	Pro	XBRL の会計チェックと計算リンクベースのチェック結果を返します。

リソース

URI	種類	目的
hub-equity://catalog/hubs	json	EN/FR のラベルとカテゴリを含む、標準化されたハブの完全なカタログです。
hub-equity://catalog/categories	json	カテゴリごとのハブ数です。
hub-equity://catalog/tool-tiers	markdown	Free と Pro のツールカタログと利用条件です。
hub-equity://schema/financial-statements	markdown	財務諸表の構造と読み取りルールです。
hub-equity://catalog/hub/{hub_code}	template	1 つのハブのカタログエントリーです。
hub-equity://entity/{entity_id}/profile	template	エンティティの完全なスナップショットです。
hub-equity://prompts/best-practices	markdown	クライアント統合向けのシステムプロンプトのガイダンスです。ツールを呼び出す前に読み込んでください。
hub-equity://prompts/tool-usage-examples	markdown	ツールごとの少数ショット例（適切な例とアンチパターン）です。
hub-equity://prompts/data-coverage	json	データセットのライブスナップショット（発行体と提出書類の件数、ソース、分類体系、会計年度の範囲）です。24 時間キャッシュされます。

プロンプト

8 つの分析テンプレート：peer_comparison、quality_of_earnings、 restatement_audit、sector_overview、valuation_screen、 goodwill_impairment_risk、working_capital_diagnostic、cash_flow_consistency。

クライアント開発者向け

ツールを呼び出す前に、hub-equity://prompts/best-practices を取得し、 その Markdown をシステムプロンプトに挿入してください。これにより、クライアントは Hub-Equity 独自のチャットと同じツールのルーティング、ソースの引用、数値の忠実性に関する ルールに従うようになります。

# Pseudo-code for a typical MCP client integration
session = mcp.connect("hub-equity-mcp")
best_practices = session.read_resource("hub-equity://prompts/best-practices")
system_prompt = "You are an assistant ...\n\n" + best_practices
# now call session.call_tool("find_entity", {"query": "AAPL"}) etc.

レート制限

モード	上限	備考
Free キー	120 リクエスト / 分	基本ツールです。
Builder キー	300 リクエスト / 分	プレミアムツールが利用可能になります。
Team キー	600 リクエスト / 分	プレミアムツールが利用可能になります。
Enterprise キー	1 000 リクエスト / 分	交渉可能です。

バケットは API キーごとに適用されます。

1 分あたりの制限による 429 が発生した場合、クライアントは RateLimitExceeded を 送出する前に、指数バックオフで最大 3 回再試行します。日次または月次の利用枠を 使い切った場合は、API のメッセージとともにただちに送出されます。

トラブルシューティング

症状	原因	対処方法
429 Too Many Requests / RateLimitExceeded	レート上限に到達しました（Free キーでは 120/分、有料キーでは 300～1 000/分）	有料プランに移行するか、ツール呼び出しの並列実行数を減らしてください。クライアントはすでに最大 3 回バックオフします。
すべてのツール呼び出しで HUBEQUITY_API_KEY is not set が表示される	クライアントの env ブロックにキーがありません	HUBEQUITY_API_KEY を設定してください。Free キーは https://hub-equity.com/settings/api-keys で 1 分で取得できます。
HubEquityRestError: HTTP 401	無効、期限切れ、または取り消し済みの hubq_ キーです（INVALID_API_KEY）	https://hub-equity.com/settings/api-keys で新しいキーを作成してください。
HubEquityRestError: HTTP 403	キーのワークスペースが Free プランで、呼び出しに Pro ツールまたは Free の上限（depth > 1、limit > 20、min_quality_grade）が必要です	プランをアップグレードするか、Free の上限内で利用してください。
本文に DAILY_QUOTA_EXCEEDED / MONTHLY_QUOTA_EXCEEDED が含まれる RateLimitExceeded	ワークスペースの利用量上限を使い切りました（Free は 1 日 200 回 / 1 か月 5 000 回、Builder は 50 000 回、Team は 1 か月 500 000 回）。再試行なしでただちに送出されます	resets_on まで待つか、プランをアップグレードしてください。
接続エラーまたはタイムアウトエラー	api.hub-equity.com への接続に関するネットワークの問題、または HUBEQUITY_API_URL の設定ミスです	接続を確認してください。HUBEQUITY_API_URL（設定されている場合）が、到達可能な https:// ホストを指していることを確認してください。
ValueError: HUBEQUITY_API_URL must use https://	キーは設定されていますが、ループバック以外のホストで URL に http:// が指定されています	https:// を使用するか、HUBEQUITY_API_URL の設定を解除してデフォルトの API にフォールバックしてください。
サーバーが Claude Desktop または Cursor に表示されない	設定 JSON のエラー、またはクライアントの PATH に pipx がありません	JSON を検証してください。クライアントが解決できない場合は、pipx（または uvx）の絶対パスを使用してください。

ローカルで実行する

python -m hub_equity_mcp.server

または MCP インスペクターを使って、対話形式で操作できます。

npx @modelcontextprotocol/inspector python -m hub_equity_mcp.server

インスペクターにはすべてのツール、リソース、プロンプトが一覧表示され、それぞれを 呼び出すことができます。

開発

pip install -e '.[dev]'
pytest tests/

テストは外部依存のない環境で実行できます。ツールのテストでは respx を使って REST API をモックするため、稼働中のバックエンドは必要ありません。

ライセンス

Apache-2.0。詳細は LICENSE と NOTICE を参照してください。このコネクターは、公開 Hub-Equity REST API を利用するオープンクライアントです。プレミアムデータへのアクセスは、サービス側の API キー、プラン、レート制限によって引き続き制限されます。