FinancialFilings

English | 简体中文

FinancialFilings MCP サーバー

FinancialFilings API 用の公式 Model Context Protocol（MCP）サーバーです。 Claude（およびMCP互換クライアント）から、世界各国の上場企業の規制関連提出書類、財務データ、企業情報に直接アクセスできます。デフォルトで厳選された17個のツール（すべての55個のツールを利用するには MCP_FULL_SURFACE=1 を設定してください）。**すべての FinancialFilings アカウントで無料です。**公式規制当局の情報を提供元としています。

---

クイックスタート

アナリスト、研究者、または公開企業の提出書類について Claude に質問したい方は、以下の手順に従ってください。

1. financialfilings.com で無料アカウントを作成します。MCP コネクターはすべての FinancialFilings ユーザーが無料で利用できます。有料プランは不要です。
2. MCP クライアントにコネクターを追加します。以下のクライアントを接続するから、お使いのものを選んでください。特によく使われる2つの方法は次のとおりです。
   • Claude.ai / Claude Desktop：Settings → Connectors → Add custom connector → URL：https://mcp.financialfilings.com/mcp
   • Claude Code：claude mcp add --transport http financialreports https://mcp.financialfilings.com/mcp
3. 求められたら、FinancialFilings アカウントでサインインします。これで完了です。

スクリーンショット付きの詳しい設定手順：financialfilings.com/integrations/claude/。

---

クライアントを接続する

これはリモートMCP サーバーです。OAuth（PKCE + Dynamic Client Registration）を使用する Streamable HTTP で動作します。コピーする API キーも、保存するシークレットもありません。接続すると、FinancialFilings アカウントでサインインするためのブラウザーが開きます。

エンドポイント： https://mcp.financialfilings.com/mcp

以下からお使いのクライアントを選んでください。掲載されていない場合は、末尾の汎用の設定を使用してください。エンドポイントとOAuthフローはどのクライアントでも同じで、異なるのは設定ファイルだけです。

Claude.ai / Claude Desktop

Settings → Connectors → Add custom connector → URL：https://mcp.financialfilings.com/mcp。求められたらサインインします。

Claude Code

claude mcp add --transport http financialreports https://mcp.financialfilings.com/mcp

セッション中に /mcp を実行して、ブラウザーでのサインインを完了します。

または、プラグインをインストールすると、同じサーバーに加えて financial-filings-research スキル（ツールのチートシートと調査ワークフロー）が追加されます。

/plugin install financialfilings --marketplace financial-reports/financial-reports-mcp-server

2.1.275 より前の Claude Code では、先にマーケットプレイスを追加します：/plugin marketplace add financial-reports/financial-reports-mcp-server、続けて /plugin install financialfilings@financialfilings を実行してください。どちらの場合も、サインインするために /mcp を一度実行します。

Codex（OpenAI）

Codex は TOML を使用します。~/.codex/config.toml（またはプロジェクトの .codex/config.toml）に追加してください。

[mcp_servers.financialreports]
url = "https://mcp.financialfilings.com/mcp"

次に認証します。Codex は、OAuth に対応するサーバーに対して OAuth ブラウザーフローを実行します。

codex mcp login financialreports

Cursor

Cursor Directoryからワンクリックでインストールするか、~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）に手動で追加してください。

{
  "mcpServers": {
    "financialfilings": { "url": "https://mcp.financialfilings.com/mcp" }
  }
}

初回使用時に、ブラウザーでOAuthが実行されます。

Kilo Code

プロジェクトの .kilocode/mcp.json（またはグローバル MCP 設定ファイル）に追加します。

{
  "mcpServers": {
    "financialreports": {
      "type": "remote",
      "url": "https://mcp.financialfilings.com/mcp"
    }
  }
}

opencode

opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "financialreports": {
      "type": "remote",
      "url": "https://mcp.financialfilings.com/mcp",
      "enabled": true
    }
  }
}

Gemini CLI

~/.gemini/settings.json：

{
  "mcpServers": {
    "financialreports": { "httpUrl": "https://mcp.financialfilings.com/mcp" }
  }
}

Hermes

Hermes の設定（YAML）の mcp_servers に追加します。

mcp_servers:
  financialreports:
    url: "https://mcp.financialfilings.com/mcp"
    auth: oauth

汎用（任意の MCP クライアント）

MCP 対応のほとんどのハーネスでは、mcpServers オブジェクトを使用します。Streamable HTTP 経由でエンドポイントを指定してください。

{
  "mcpServers": {
    "financialreports": {
      "type": "streamable-http",
      "url": "https://mcp.financialfilings.com/mcp"
    }
  }
}

ネイティブのリモート MCP OAuth に対応しているクライアント（Claude、Cursor、Windsurf、VS Code、opencode、codex mcp login 経由の Codex）では、ブラウザーでのサインインが自動的に実行されます。OpenClaw やその他の MCP 対応ハーネスでは、このブロックにコネクターの URL を指定して使用し、プロンプトが表示されたら OAuth を完了してください。正確なファイルの場所については、クライアント独自の MCP 設定ドキュメントをご確認ください。

トラブルシューティング：「Client Not Registered」

サインイン時に Client Not Registered というタイトルのページが表示され、「クライアント ID … がサーバーのクライアントレジストリに見つかりません」と表示される場合、クライアントはこのサーバーに登録されていないクライアント情報を提示しています。

コネクターを削除して、もう一度追加してください。 解決する方法はこれだけで、数秒で完了します。

クライアント	対処方法
ChatGPT / OpenAI	Settings → Connectors → FinancialFilings を削除（名前変更前に接続した場合は FinancialReports と表示）→ https://mcp.financialfilings.com/mcp を指定して再追加し、もう一度サインインします。
Claude.ai / Claude Desktop	Settings → Connectors → FinancialFilings を削除（名前変更前に接続した場合は FinancialReports と表示）→ 再追加して、もう一度サインインします。
Claude Code / Codex / Cursor / opencode	サーバーを削除して再追加するか（例：claude mcp remove financialreports を実行してから再追加）、クライアントのログインコマンドをもう一度実行します（codex mcp login financialreports）。

エラーページに記載されていない点が 2 つあります。

• 自然に解決することはなく、再試行しても効果はありません。 サインインはブラウザーで行われるため、クライアントは失敗したことを認識できません。届かないコールバックを待ち続け、無効な ID をそのまま再送します。再起動しても解決しません。ホスト型コネクター（ChatGPT、Claude.ai）は登録情報をサーバー側に保持しているため、コネクターを削除する以外に登録情報を消去する方法はありません。
• アカウントに問題はなく、データにも影響はありません。 再追加すると新しい登録が作成され、これまでどおり動作します。

2026 年 7 月 14 日以降に影響を受けた場合： キャッシュのフェイルオーバーにより、保存されていたクライアント登録情報が失われました。その後、サインインは正常に動作しています。この日より前に追加されたコネクターのみ、上記の削除と再追加が必要です。

---

提供される機能

デフォルトでLLMから呼び出せる17個のツール — アナリストが実際に使う、厳選された機能です。

領域	ツール数	用途
企業	5	名称／ティッカー／ISINで検索、企業の詳細プロフィールを取得、正規化された財務データを取得、次回の年次報告書を予測、識別子のリストを企業IDに一括変換
提出書類	4	提出書類の一覧表示、取得、Markdown形式の内容の取得（最大150K文字）、単一の提出書類内をキーワード検索
ISIN	2	ISINで検索、二重上場の一覧表示
参照分類	2	提出書類のカテゴリーと種類
アカウント	1	今回のサイクルにおけるAPIとMCPの利用料金、利用上限、残りの無料クレジットを確認（無料、請求対象外）
ガイド	3	提出書類の種類の分類、ISIC産業分類、Markdown取得戦略 — MCPリソースを読み込めないツールのみのクライアント向けに、呼び出し可能なリファレンスを提供

MCP_FULL_SURFACE=1 を設定すると、全55個のツールが利用できるようになります。ISICの部／分野／グループ／クラス階層、その他の参照データ（国、言語、情報源、項目の定義、提出書類の履歴）、ユーザーごとのウォッチリスト、Webhookのサブスクリプション、企業統合の監査フィード、取引所ごとの証券上場情報、エージェント向けアカウント登録エンドポイント（サインアップ、キーの取得、キーのローテーション、チェックアウトリンク、所有者確認、ステータス）、filings_markdown_search の背後にある未加工の filings_markdown_search_retrieve エンドポイント、および filings_document_retrieve（JSONではなくファイルを返します）が含まれます。

提供されるツール群は、コミット済みでレビュー済みの FinancialFilings OpenAPIスキーマのスナップショット（scripts/openapi.snapshot.json。CIとDockerビルドでは FR_PIN_SCHEMA=1 を指定して固定）から生成されるため、結果は決定的で、再ビルド時に気付かないうちに変更されることはありません。

コンパニオンスキル

このリポジトリには Agent Skill — financial-filings-research — が含まれています。このスキルは、アナリストが実際に行うワークフロー（企業検索、提出書類の要約、複数企業の財務比較、ISIC産業スクリーニング、提出書類のモニタリング）に沿って、Claudeがこれらのツールを組み合わせる方法を教えます。ユーザーが企業名、ティッカー、ISIN、提出書類の種類、または財務指標に言及すると、自動的に有効になります。

---

アーキテクチャ

┌──────────────────┐     OAuth (PKCE + DCR)      ┌──────────────────┐
│  Claude / MCP    │  ───────────────────────►   │  AWS Cognito     │
│  client          │                              │  (user pool)     │
└────────┬─────────┘                              └────────┬─────────┘
         │  Streamable HTTP /mcp                           │
         │  + bearer token                                 │
         ▼                                                 │
┌──────────────────┐     verify subscription tier          │
│  This server     │  ───────────────────────────────────► │
│  (FastAPI +      │                                       ▼
│   FastMCP)       │     proxy bearer token         ┌──────────────────┐
│                  │  ─────────────────────────►    │  api.            │
│  17 tools        │                                │  financial-      │
│  generated from  │                                │  reports.eu      │
│  OpenAPI schema  │                                │  (first-party)   │
└──────────────────┘                                └──────────────────┘

主な設計上の判断：

• ツールは手書きではなく、生成されます。 scripts/generate_mcp_tools.py がOpenAPIスキーマを読み込みます。このスキーマはCIとDockerビルドで FR_PIN_SCHEMA=1 を指定してコミット済みのスナップショットに固定されており、src/financial_reports_mcp.py を生成します。デフォルトのツール群は、17個のツールに絞って厳選されています。MCP_FULL_SURFACE=1 を指定すると、すべてのツールが生成されます。ジェネレーターの _PRUNED_EXCLUDE は拒否リストであるため、スナップショット更新のプルリクエストで明示的に除外しない限り、新たに追加された上流エンドポイントは厳選されたツール群に含まれる点に注意してください。
• セッショントークンを保存せず、Bearerトークンをプロキシします。 ユーザーのCognitoアクセストークンは、呼び出しのたびに上流APIへ転送されます。会話データは保存せず、API応答もサーバー側ではキャッシュしません。
• サブスクリプションの判定はプロセス内で行います。 Cognitoの sub からティアへの対応を15秒間LRUキャッシュし、ツール呼び出しのたびにFR APIへ繰り返しリクエストするのを避けます。
• 同一オリジンのアセットプロキシです。 コネクターUIと /consent ページをクロスオリジンCSPの制約なく表示できるよう、/favicon.ico、/icon.png、/icon-{32,192,512}.png はこのオリジンから配信されます（CDNからプロキシしてキャッシュします）。

---

MCP 仕様への準拠

MCP 2025-11-25 仕様に準拠しています。

• ✅ ストリーム可能な HTTP トランスポート — MCP-Protocol-Version のエコーバックを伴う POST /mcp。未対応バージョンには 400 を返します
• ✅ OAuth 2.0 — RFC 7591 による動的クライアント登録と PKCE S256
• ✅ RFC 9728 保護リソースメタデータ — /.well-known/oauth-protected-resource と /.well-known/oauth-protected-resource/mcp の両方で提供
• ✅ ツールのアノテーション — すべてのツールに title と readOnlyHint または destructiveHint を設定
• ✅ outputSchema — 6 つの構造化コンテンツツール（companies_list、companies_retrieve、companies_financials_retrieve、filings_list、filings_retrieve、isins_list）
• ✅ オリジン検証 — 認識されないオリジンには 403 を返し、未認証のリクエストには適切な WWW-Authenticate ヘッダーとともに 401 を返します
• ✅ 複数サイズのコネクターアイコン — initialize レスポンスで 32×32、192×192、512×512 の PNG を通知

CI では、すべての PR で上記の項目を検証します。

---

ツールカタログ

以下のリストは、ビルドごとに scripts/generate_mcp_tools.py によって再生成されます。マーカー間を手動で編集しないでください。

アカウント

• usage_retrieve — API の使用状況と支出を取得

企業

• companies_financials_retrieve — 企業の財務情報を取得
• companies_list — 企業一覧を取得
• companies_next_annual_report_retrieve — 次回の年次報告書を予測
• companies_resolve_create — 識別子から企業を一括特定
• companies_retrieve — 企業の詳細情報を取得

提出書類のカテゴリ

• filing_categories_list — 提出書類のカテゴリ一覧を取得

提出書類の種類

• filing_types_list — 提出書類の種類一覧を取得

提出書類

• filings_list — 提出書類一覧を取得
• filings_markdown_retrieve — 提出書類の Markdown を取得
• filings_retrieve — 提出書類の詳細情報を取得

ISIN

• isins_list — ISIN 一覧を取得
• isins_retrieve — ISIN を取得

---

プロンプトの例

接続したら、次のように試してみてください。

• 「Apple の最新の 10-K を探し、前年比で変化したリスク要因を要約してください。」
• 「ASML の企業詳細をすべて取得してください。」
• 「最新会計年度の Iberdrola、Engie、Enel、RWE の純有利子負債を比較してください。」
• 「過去 6 か月に年次報告書を提出した EU の航空会社を一覧表示してください。」
• 「過去 30 日間の Tesla のインサイダー取引に関する提出書類を表示してください。」
• 「ウォッチリスト内の企業が 8-K を提出したら通知してください。」
• 「Volkswagen AG の LEI は何ですか？」

---

セルフホスティング

セルフホスティングには独自の AWS Cognito ユーザープールの構築が必要で、主にフォークして別の上流 API に合わせて変更する場合に役立ちます。FinancialFilings API については、mcp.financialfilings.com のホスト型サーバーがサポート対象の方法です。

セルフホスティングの詳細なドキュメント（Docker、Cognito の設定、環境変数、CDN／アイコンの設定）：docs/SELF-HOSTING.md。

---

開発

ワンショットの初期設定（venv → 依存関係 → 環境チェック → 生成 → 実行）：

cp .env.example .env   # fill in Cognito values first; see docs/SELF-HOSTING.md
make dev               # creates .venv, installs, validates env, regenerates, serves on :8000
# MCP endpoint: http://localhost:8000/mcp

または、手順を分けて実行します。

# 1. Setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -r requirements-test.txt

# 2. Configure
cp .env.example .env  # then fill in Cognito values; see docs/SELF-HOSTING.md

# 3. Generate the MCP module from the OpenAPI schema
python scripts/generate_mcp_tools.py

# 4. Run tests
pytest

# 5. Run locally
python -m uvicorn src.financial_reports_mcp:app --host 0.0.0.0 --port 8000
# MCP endpoint: http://localhost:8000/mcp

CI では、すべての PR でユニットテスト一式と Docker-Compose によるエンドツーエンドテスト（Redis 使用）を実行します。.github/workflows/ci.yml を参照してください。

個人用 API キーを使用したローカル開発

再起動のたびに Cognito OAuth の手順を経由せずに、実際のバックエンドに対してジェネレーター、ツール、またはプロンプトを反復して開発できるよう、サーバーでは開発専用の DEV_MODE_API_KEY 環境変数をサポートしています。設定すると、既存の /mcp エンドポイントでは JWT 検証がスキップされ（subscription_required と _authorize_or_raise の両方の処理経路）、キーは X-API-Key として API_BASE_URL に転送されます。

これはメンテナー向けの利便機能であり、本番環境での認証方法ではありません。 MCP_BASE_URL に本番ホスト名（mcp.financialfilings.com）が含まれている場合、モジュールのインポートは拒否されます。

1. 個人用の FinancialFilings API キーを .env に追加します。

   DEV_MODE_API_KEY=fr_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   MCP_BASE_URL=http://localhost:8000
   

2. サーバーを再生成して起動します（バイパスが有効でも OAuth プロキシモジュールは読み込まれるため、Cognito の変数は引き続き設定する必要があります）。

   make regen
   python -m uvicorn src.financial_reports_mcp:app --host 0.0.0.0 --port 8000 --reload
   

3. Claude Code でローカルインスタンスを指定します。

   claude mcp add --transport http financialfilings-local http://localhost:8000/mcp
   

   リポジトリの .mcp.json ではなく、このように開発者ごとに追加してください。このファイルには本番サーバーのみを記載しています。リポジトリをスキャンするディレクトリ（例：Cursor Directory）は、ファイル内のすべてのエントリを公開インストール用として掲載するためです。

本番環境向けのヘッドレス／API キー認証（リクエストごとに X-API-Key を使用する並行 /mcp/apikey エンドポイント）は #28 で追跡されており、この開発モードの簡易機能とは別の機能です。

よくある作業

# Regenerate tools after the OpenAPI schema changes
python scripts/generate_mcp_tools.py

# Run only fast unit tests
pytest tests/test_*.py

# Run end-to-end tests with Redis (requires Docker)
make e2e

---

変更の評価

このサーバーのベンチマークには financial-reports/mcp-evals（非公開）を使用します。複数モデルのスコアカード（タスクの成功率、ツール選択の正確性、パスの一貫性、トークン数／ターン数／レイテンシ）はこのリポジトリではなく、そちらで管理されています。ツールの説明、プロンプト、またはジェネレーターへの変更をマージする前に、ハーネスを本番環境またはローカルの開発用 MCP に対して実行し、スコアカードを比較してください。

このリポジトリに含まれるのは、tests/eval/ にある決定論的なプロンプト登録テストです。高速で、API キーは不要であり、すべての PR で実行されます。リポジトリ間のワークフローについては、tests/eval/README.md を参照してください。

---

セキュリティ

このサーバーは OAuth フローとベアラートークンを扱います。脆弱性を発見しましたか？公開の issue は作成しないでください。 責任ある脆弱性開示の手順については、SECURITY.md を参照してください。

サーバー側の保証：

• ベアラートークンはリクエストごとにプロキシされ、ログへの記録や永続化は行われません。
• HTTPS が適用されます（HTTP はエッジで HTTPS にリダイレクトされます）。
• HTML レスポンスには CSP が適用されます（default-src 'none'。同一オリジンのアセットのみ許可されます）。
• オリジン検証により、認識されていないオリジンからのリクエストは拒否されます。
• すべての暗号処理は、標準ライブラリと AWS SDK に依存しており、独自の暗号処理はありません。

---

貢献

貢献を歓迎します。開発環境のセットアップ、再生成→テスト→PR のワークフロー、歓迎される変更（テスト、ドキュメント、ジェネレーターの改善、scripts/generate_mcp_tools.py にある手動調整済みのツール説明）と却下される変更（手動編集された src/financial_reports_mcp.py。このファイルは自動生成され、ビルドのたびに上書きされます）については、CONTRIBUTING.md を参照してください。

---

プロジェクトの状況

• 本番環境：https://mcp.financialfilings.com/mcp で稼働中
• 掲載先：Claude コネクターディレクトリ、Cursor Directory
• 仕様への準拠：MCP 2025-11-25
• テスト済み：Claude.ai、Claude Code、Claude Desktop、Cursor、Windsurf。Codex、Kilo Code、opencode、Gemini CLI、Hermes 用の設定スニペットも用意されています（クライアントを接続するを参照）。

---

ライセンス

MIT — © FINANCIALREPORTS PTE. LTD.

---

謝辞

この公式版の開発のきっかけとなった概念実証版として、コミュニティによって構築された元の MCP サーバーを公開してくださった@itisaevalexに、心より感謝いたします。

FastMCP、FastAPI、およびModel Context Protocolを基盤に構築されています。