financial-hub-mcp

Financial Hub MCP Server

財務データを集約する TypeScript 製 MCP サーバーです。あらゆる MCP 対応 AI アシスタントを、SEC EDGAR の提出書類、XBRL 財務諸表、FRED の経済指標、リアルタイムの市場データに接続します。XBRL の正規化、ファクトの重複排除、分析値の算出、株式スクリーニング、レート制限対策を標準搭載しています。

主な概念

SEC EDGAR

SEC EDGAR のデータはすべて、SEC の無料公開 API data.sec.gov から直接取得します。API キーは不要です。サーバーは次の処理を自動で行います。

• XBRL コンセプトの解決 — 同じ指標でも、企業によって異なる XBRL タグが使われます。サーバーは 20 を超える財務コンセプトを横断して正規化します（たとえば、revenue は Revenues、RevenueFromContractWithCustomerExcludingAssessedTax、SalesRevenueNet、その他 11 種類のバリエーションに対応します）。
• ファクトの重複排除 — 生の XBRL データには、重複する 10-K／10-Q の提出書類や修正書類に由来する値が含まれています。サーバーはこれらを集約し、会計期間ごとに値を 1 つに整理します。
• レート制限 — SEC の制限は毎秒 10 リクエストです。上限付きキューイング（保留中のリクエストは最大 50 件、タイムアウトは 30 秒）を備えたトークンバケット方式のレートリミッターにより、IP アドレスのブロックを防ぎます。

FRED

FRED（Federal Reserve Economic Data）は、100 を超える情報源から 800,000 件以上の時系列データを提供します。fred.stlouisfed.org から無料の API キーを取得する必要があります。レート制限は毎分 120 リクエストです（毎秒 2 リクエストのトークンバケット方式で適用）。9 つのカテゴリにわたる約 50 件の主要な経済指標を厳選したカタログも含まれており、API 呼び出しなしで閲覧できます。

Finnhub 市場データ

Finnhub API を通じて、リアルタイムの株価、企業プロフィール、市場ニュース、インサイダー取引、財務指標を取得できます。無料プランでは、クレジットカード登録なしで毎秒 30 回の API 呼び出しが可能です。サーバーは上限を十分に下回るよう、毎秒 25 リクエストに制限しています。株価はキャッシュしません（古い株価はキャッシュなしよりも望ましくないため）。一方、プロフィール（24 時間）、ニュース（5 分）、財務指標（1 時間）には、それぞれ適切な TTL を設定しています。

キャッシュ

TTL で有効期限を管理するインメモリ LRU キャッシュにより、重複する API 呼び出しを削減します。

キャッシュ	TTL	最大エントリ数	ペイロードサイズ
企業ファクト	1 時間	10	各 20～50 MB
企業提出書類	1 時間	30	各約 50 KB
企業ティッカー	24 時間	1	約 3 MB
FRED 系列メタデータ	6 時間	100	各約 1 KB
FRED 観測値	1 時間	50	各約 5 KB
市場プロフィール	24 時間	50	各約 1 KB
市場ニュース	5 分	10	各約 5 KB
インサイダー取引	1 時間	30	各約 3 KB
基本財務情報	1 時間	30	各約 2 KB

エビクションには LRU 方式を採用しています。頻繁にアクセスされたエントリは読み取り時に優先度が上がるため、容量が上限に達すると、最も長い間使われていないエントリが削除されます。期限切れのエントリは、書き込みのたびに事前に走査して削除します。

API

ツール

• search_companies

  • SEC に登録された企業を社名またはティッカーで検索します
  • 入力：query（文字列）
  • 一致した企業名、ティッカー、CIK 番号を返します

• get_company_filings

  • 企業の最近の SEC 提出書類を取得します
  • 入力：
    • cik（文字列）：SEC の企業固有識別子
    • formType（文字列、省略可）：フォームの種類で絞り込みます（10-K、10-Q、8-K、DEF 14A）
  • 提出書類のメタデータ（フォームの種類、日付、ドキュメントへのリンク）を返します

• get_financial_metric

  • トレンド分析付きで、重複を排除した財務指標の過去の値を取得します
  • 入力：
    • cik（string）：企業のCIK番号
    • concept（string）：わかりやすい名前または生のXBRLタグ
    • taxonomy（string、optional）：XBRLタクソノミ（デフォルト：us-gaap）
    • annualOnly（boolean、optional）：年次データポイントのみを返します
  • わかりやすい名前として、revenue、net_income、gross_profit、operating_income、eps、total_assets、total_liabilities、stockholders_equity、cash、long_term_debt、current_assets、current_liabilities、operating_cash_flow、capex、shares_outstandingを受け付けます
  • 生のXBRLタグ（Revenues、NetIncomeLoss、Assetsなど）も受け付けます
  • 重複を排除した値（会計期間ごとに1つ）、前年比成長率、トレンドの方向を返します

• get_financial_summary

  • 算出済みの比率を含む、包括的な財務スナップショットを取得します
  • 入力：cik（string）
  • 最新の指標を返します：売上高、純利益、資産、負債、純資産、現金、負債、EPS、営業キャッシュフロー、フリーキャッシュフロー
  • 算出済みの比率：利益率、負債資本比率、流動比率、ROE、ROA
  • すべての値は、直近の年次報告書から重複を排除して取得されます

• get_company_facts_summary

  • 企業について利用可能なすべてのXBRLデータの簡潔な一覧を取得します
  • 入力：
    • cik（string）：企業のCIK番号
    • limit（number、optional）：返す概念の最大数（デフォルト40、最大100）
  • 概念名、最新の値、データポイント数を返します。時系列データ全体は返しません
  • 特定の指標を詳しく調べる前に、利用可能なデータを把握するために使用します

• analyze_financials

  • 算出済みの比率、成長指標、健全性スコアを用いて、詳細な財務分析を行います
  • 入力：cik（string）
  • 返される内容：
    • 財務比率：利益率、粗利益率、営業利益率、ROE、ROA、負債資本比率、流動比率
    • 成長分析：前年比成長率、3年および5年のCAGR、トレンド検出
    • 説明要因付きの総合健全性評価（A〜F）
  • 内部でPromise.allSettledを使用するため、個々の指標の取得に失敗しても分析全体は停止しません

• compare_companies

  • 2〜5社の財務状況を並べて比較します
  • 入力：ciks（string[]、CIK番号を2〜5個）
  • 売上高、利益、資産、現金、EPS、フリーキャッシュフロー、比率、健全性スコアを比較します
  • 売上高、収益性、成長、総合的な健全性に基づいて優位な企業を特定します
  • 個々の企業の取得失敗は個別に処理され、部分的な比較結果も返されます

• search_filings

  • SEC EDGARのすべての提出書類を対象に、ページネーション付きで全文検索します
  • 入力：
    • query（string）：検索語
    • forms（string、optional）：カンマ区切りの書式タイプ
    • startDate（string、optional）：YYYY-MM-DD
    • endDate（string、optional）：YYYY-MM-DD
    • limit（number、optional）：1ページあたりの結果数（デフォルト20、最大50）
    • offset（number、optional）：ページネーション用に結果をN件スキップ
  • 結果の配列と、ページネーション用のヒット総数を返します
  • 2001年以降のすべての提出書類の全文を検索します

• screen_stocks

  • 取引所、業種、名称、財務健全性でSEC登録企業をスクリーニングします
  • 入力：
    • exchange（string、optional）：取引所で絞り込みます（例：NYSE、Nasdaq）
    • industry（string、optional）：SIC業種グループ（technology、finance、healthcare、energy、manufacturing、retail、transportation、utilities、services、public_admin）
    • nameContains（string、optional）：企業名に対する大文字・小文字を区別しない部分文字列一致
    • minHealthScore（number、optional）：財務分析による最低健全性評価（0〜100）
    • limit（number、optional）：結果の最大数（デフォルト20、最大50）
  • 2段階のスクリーニングを行います。まず、10,000社以上を対象にクライアント側で即時に絞り込み、次に必要に応じてSEC APIを通じて業種や健全性指標で詳しく絞り込みます

• get_corporate_events

  • 重要度の分類付きで、直近の8-K企業イベントを取得します
  • 入力：
    • cik (string)：企業のCIK番号
    • significance (string, optional)：high、medium、lowの重要度で絞り込みます
    • limit (number, optional)：イベントの最大件数（デフォルト15、最大50）
  • SECの25種類の8-K項目番号を、人が理解しやすいカテゴリと重要度に分類します
  • 重要度「高」：CEOの交代、M&A、破産、重要な契約、監査人の変更
  • 重要度「中」：決算発表、退任、資産売却、修正
  • 既存の提出データを使用するため、追加のAPI呼び出しは不要です

• search_economic_data

  • FREDデータベースから経済データの系列を検索します
  • 入力：query (string)
  • 系列ID、タイトル、頻度、単位を返します
  • 返された系列IDをget_economic_dataで使用します

• get_economic_data

  • FRED経済データ系列の時系列観測値を取得します
  • 入力：
    • seriesId (string)：FRED系列ID
    • startDate (string, optional)：YYYY-MM-DD
    • endDate (string, optional)：YYYY-MM-DD
  • 主な系列：GDP、CPIAUCSL（CPI）、UNRATE（失業率）、FEDFUNDS、DGS10（10年国債）、SP500、MORTGAGE30US

• get_stock_quote

  • Finnhubからリアルタイムの株価を取得します
  • 入力：symbol (string)：株式ティッカー（例：AAPL、MSFT、GOOGL）
  • 現在の株価、日次変動、変動率、日中の高値・安値、始値、前日終値を返します
  • ライブデータです。キャッシュは使用しません

• get_market_news

  • 最新の金融ニュース見出しを取得します
  • 入力：
    • symbol (string, optional)：企業固有のニュースを取得する場合は株式ティッカーを指定します。市場全般のニュースを取得する場合は省略します
    • category (string, optional)：general、forex、crypto、merger（市場全般のニュースのみ）
  • 見出し、概要、情報源、URL、日時を含む最大20件の記事を返します

• get_insider_transactions

  • 企業の直近のインサイダー取引状況を取得します
  • 入力：symbol (string)：株式ティッカー（例：AAPL、TSLA）
  • インサイダーの氏名、株式数、取引日、価格、売買コードを返します
  • 取引コード：P = 購入、S = 売却、M = オプション行使、A = 付与／報奨、G = 贈与、F = 税金の源泉徴収

• get_company_overview

  • 企業プロフィール、市場指標、同業他社をまとめた包括的な企業概要を取得します
  • 入力：symbol (string)：株式ティッカー（例：AAPL、MSFT）
  • 企業名、取引所、業種、時価総額、PER、ベータ値、52週間の値幅、EPS、配当利回り、同業他社のティッカーを返します
  • Finnhub APIを4回並列で呼び出し（プロフィール、財務情報、同業他社、株価）、データを統合します

リソース

• sec://company/{ticker}

  • SECメタデータと最近の提出書類を含む企業プロフィール
  • 含まれる情報：企業名、CIK、ティッカー、取引所、SICコード、会計年度末、直近10件の提出書類
  • リソースに対応する任意のMCPクライアントから参照できます

• fred://catalog/{category}

  • カテゴリ別に整理されたFRED経済指標を参照します
  • カテゴリ：gdp、labor、inflation、rates、housing、markets、money、trade、consumer
  • 系列ID、タイトル、頻度、説明を返します。API呼び出しは不要です

• fred://indicator/{seriesId}

  • 最新の観測値を含むFRED指標の詳細
  • カタログの系列メタデータと、直近10件のデータポイントを返します
  • 時系列全体を取得する前に、特定の指標を確認するために使用します

プロンプト

• financial_analysis

  • 企業の財務健全性を段階的に分析します
  • 入力：ticker (string)
  • 収益の推移、収益性、貸借対照表の健全性、リスク評価を順に確認します

• peer_comparison

  • 2社を並べて比較します
  • 入力：ticker1 (string)、ticker2 (string)

• economic_overview

  • 米国の現在の経済状況を示すダッシュボード
  • 入力は不要です
  • GDP、失業率、CPI、フェデラルファンド金利、国債利回り、住宅ローン金利を取得します

ツールのアノテーション

すべてのツールで、エージェントを安全に組み合わせるための MCP ToolAnnotations を設定しています。

ヒント	値	理由
readOnlyHint	true	すべてのツールは読み取り専用で、データは変更されません
destructiveHint	false	データは破壊されません
idempotentHint	true	同じ入力からは同じ出力が生成されます
openWorldHint	true	すべてのツールは外部 API を呼び出します

エラー処理

失敗時、すべてのツールは isError: true を含む MCP 準拠のエラーエンベロープを返します。

{
  "content": [{ "type": "text", "text": "SEC EDGAR request failed: 404 Not Found" }],
  "isError": true
}

これにより、エージェントのループを中断する不透明なトランスポートレベルの JSON-RPC エラーを返す代わりに、LLM は意味のあるエラーメッセージを受け取り、パラメーターを修正して再試行できます。

Claude Desktop での使用方法

次の内容を claude_desktop_config.json に追加してください。

NPX

{
  "mcpServers": {
    "financial-hub": {
      "command": "npx",
      "args": ["-y", "financial-hub-mcp"],
      "env": {
        "FRED_API_KEY": "your-free-api-key",
        "SEC_USER_AGENT_EMAIL": "[email protected]",
        "FINNHUB_API_KEY": "your-free-api-key"
      }
    }
  }
}

VS Code での使用方法

手動でインストールする場合は、ユーザーレベルの MCP 設定ファイルに設定を追加してください。コマンドパレットを開き（Ctrl + Shift + P）、MCP: Open User Configuration を実行してから、次の内容を追加してください。

NPX

{
  "servers": {
    "financial-hub": {
      "command": "npx",
      "args": ["-y", "financial-hub-mcp"],
      "env": {
        "FRED_API_KEY": "your-free-api-key",
        "SEC_USER_AGENT_EMAIL": "[email protected]",
        "FINNHUB_API_KEY": "your-free-api-key"
      }
    }
  }
}

VS Code の MCP 設定について詳しくは、VS Code 公式 MCP ドキュメントを参照してください。

環境変数

変数	必須	説明
SEC_USER_AGENT_EMAIL	はい	SEC EDGAR API のコンプライアンス対応に使用するメールアドレスです。設定されていない場合、サーバーは直ちに終了します。SEC EDGAR は、User-Agent ヘッダーが欠落している、または汎用的なリクエストを拒否します。
FRED_API_KEY	FRED ツールで必要	fred.stlouisfed.org から取得できる、無料の 32 文字のキーです。キーがなくてもサーバーは起動しますが、実行時に FRED ツールが明確なエラーメッセージとともに失敗します。
FINNHUB_API_KEY	マーケットツールで必要	finnhub.io から取得できる無料の API キーです。株価、マーケットニュース、インサイダー取引、企業概要の取得に必要です。キーがなくてもサーバーは起動しますが、実行時にマーケットツールが失敗します。

アーキテクチャ

src/
├── index.ts              # Entry point — startup validation, MCP server init
├── rate-limiter.ts       # Token-bucket rate limiter with bounded queue + timeout
├── cache.ts              # In-memory TTL cache with proactive eviction
├── edgar/
│   ├── client.ts         # SEC EDGAR HTTP client (rate-limited, cached)
│   ├── tools.ts          # MCP tool registrations (12 tools, isError envelopes)
│   ├── resources.ts      # MCP resource templates (company profiles)
│   ├── xbrl.ts           # XBRL fact deduplication, growth, trend detection
│   ├── concepts.ts       # Concept alias normalization (20+ financial concepts)
│   ├── analytics.ts      # Computed ratios, health scoring, company comparison
│   ├── events.ts         # 8-K corporate event classification (25 item types)
│   └── screening.ts      # Stock screening by exchange, industry, health score
├── fred/
│   ├── client.ts         # FRED HTTP client (rate-limited, cached)
│   ├── tools.ts          # FRED MCP tool registrations
│   ├── catalog.ts        # Curated catalog of ~50 essential FRED indicators
│   └── resources.ts      # FRED MCP resource templates (catalog + indicators)
├── market/
│   ├── client.ts         # Finnhub HTTP client (rate-limited, cached)
│   └── tools.ts          # Market data MCP tool registrations (4 tools)
└── prompts.ts            # Financial analysis prompt templates

データパイプライン

SEC EDGAR の生の XBRL データは、いくつかの処理段階を経ます。

1. レート制限付きの取得 — トークンバケットにより、SEC の 10 req/s の制限を超えないようにします。保留中のリクエストが 50 件を超えた場合、または待ち時間が 30 秒を超えた場合、キューはリクエストを拒否します。
2. キャッシュ — 大きなペイロードによる OOM を避けるため、企業のファクトデータを 1 時間キャッシュし、エントリー数を最大 15 件に制限します。
3. 概念の解決 — revenue のようなわかりやすい名前を、us-gaap タクソノミー全体の既知の XBRL タグのバリエーションにマッピングします。
4. 重複排除 — 重複する 10-K／10-Q／修正申告の値を、会計期間ごとに 1 つにまとめます。10-Q より 10-K を優先し、提出日が早いものより新しいものを優先します。
5. 分析 — 整理されたデータから、成長率、CAGR、財務比率、健全性スコアを算出します。
6. シリアル化 — コンテキストウィンドウの使用量を最小限に抑えるため、JSON を最小化して出力します。

ソースからのビルド

git clone https://github.com/ykshah1309/financial-hub-mcp.git
cd financial-hub-mcp
npm install
npm run build

ローカルで実行するには：

FRED_API_KEY=your-key SEC_USER_AGENT_EMAIL=your-email FINNHUB_API_KEY=your-key node dist/index.js

コントリビューション

プルリクエストを歓迎します。開発の進め方、コミットのスタイル、PR チェックリストについては、CONTRIBUTING.md を参照してください。参加することで、行動規範に同意したものとみなされます。

セキュリティ

セキュリティ上の問題は非公開で報告してください。詳細は SECURITY.md を参照してください。脆弱性や認証情報の漏えいについて、公開の課題を作成しないでください。

変更履歴

リリースノートについては、CHANGELOG.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。

バッジ