SEC Intelligence

🔎 SEC Intelligence MCP — 文書に基づく金融 AI

SEC 提出書類（10-K、10-Q、8-K）について、Claude Desktop に実際の質問をしてみましょう。実際の提出書類の本文から直接引用した回答が得られ、すべての主張に正確なセクション（可能な場合はページも）の引用が付きます。学習データに基づく要約ではありません。推測でもありません。

今すぐ試す： uvx sec-intelligence-mcp — 下記のクイックインストールをご覧ください。

どこが違うのか

多くの金融関連 MCP サーバーはデータ API のラッパーで、データベースから数値（売上高、EPS、株価）を返します。調査した中で実際の提出書類を読み込むものはなく、そのため、企業の経営陣が実際に述べた内容を理解しなければ答えられない質問、たとえば「NVIDIA の経営陣はデータセンターの売上急増をどのように説明しましたか？」や「Amazon の今後の業績見通しのトーンは四半期ごとに変化しましたか？」には答えられません。

このサーバーは実際の提出書類の本文を取得して引用し、すべての主張に引用を付けます。また、取得した文章に回答が含まれていない場合、既存の知識や一般知識を使わないよう回答生成プロンプトで明示的に指示しています。この点は実際に検証済みです。NVIDIA の存在しない「Mars operations」について質問すると、回答を捏造せず「提出書類には記載されていません」と正しく返します。さらに、この主張を述べるだけでなく、実際の50件の質問で評価する自動 RAGAS 評価ハーネスも備えています（評価結果をご覧ください）。

---

🚀 クイックインストール

PyPI で公開されています：https://pypi.org/project/sec-intelligence-mcp/。クローンもビルド手順も不要です。
uv が必要に応じて取得し、実行します。

uvx sec-intelligence-mcp

インストールはこれで完了です。あと2つ設定すれば、Claude Desktop ですぐに使えます。

1. 無料の API キーを取得する

4つすべて、合計5分もかからずに取得できます。クレジットカードは一切必要ありません。

変数	取得先	必須？
GEMINI_API_KEY	https://aistudio.google.com/apikey — Google アカウントでサインイン	はい
QDRANT_URL	Docker で Qdrant をローカル実行する場合は http://localhost:6333（docker run -p 6333:6333 qdrant/qdrant）、または https://cloud.qdrant.io の無料クラスター URL	はい
LANGFUSE_SECRET_KEY / LANGFUSE_PUBLIC_KEY	https://cloud.langfuse.com — 無料プランでプロジェクトを作成し、Settings → API Keys から両方のキーをコピー	はい
QDRANT_API_KEY	ローカルの Docker ではなく Qdrant Cloud を使う場合のみ	いいえ

Docker を使えない場合や、Qdrant への登録を省略したい場合は、下記のQdrant の起動の注記をご覧ください。

2. Claude Desktop を接続する

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

{
  "mcpServers": {
    "sec-intelligence-mcp": {
      "command": "uvx",
      "args": ["sec-intelligence-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "QDRANT_URL": "http://localhost:6333",
        "LANGFUSE_SECRET_KEY": "your-key",
        "LANGFUSE_PUBLIC_KEY": "your-key"
      }
    }
  }
}

Claude Desktop を再起動し、ツール一覧（ハンマーアイコン）を開いて、ping ツールを備えた sec-intelligence-mcp が表示されていることを確認します。これにより、実際の質問に使う前に接続が機能していることを確認できます。

3. 試してみる

各セッションでは、質問したい企業の情報を最初に取り込みます。これにより提出書類がインデックス化され、検索できるようになります。その後は、英語で普通に質問するだけです。

あなた： NVIDIA の直近2件の年次提出書類を取り込んで

Claude （ingest_company_filings を呼び出し）：NVIDIA の提出書類を2件インデックス化しました。FY2024 の 10-K から312チャンク、FY2023 の10-Kから287チャンクです。

あなた： 輸出規制によるリスクについて、何と述べていますか？

Claude （analyze_filing を呼び出し）：NVIDIA の FY2024 10-K は、輸出規制を主要なリスクとして挙げています。「米国政府は当社製品の輸出に対する規制を課しており、今後も課す可能性があります……中国、香港、ロシアへの制限は、当社の売上高に重大な影響を与えています。」— [項目1A — リスク要因]

あなた： AMD と比べるとどうですか？

Claude （compare_companies を呼び出し）：[各社の提出書類を引用した、根拠に基づく比較回答]

プロンプトの調整も特別な構文も必要ありません。質問に応じて Claude が適切なツールを自動的に選びます。

---

🧰 利用可能なツール

ツール	機能	質問の例
ingest_company_filings	企業の最新の SEC 提出書類を取得、解析、インデックス化します	「NVIDIA の直近 3 件の 10-K を取り込んで」
search_filings	取り込み済みの提出書類をセマンティック検索し、引用付きの抜粋を返します	「Apple の 10-K から AI 投資に関する記述を検索して」
analyze_filing	特定の質問に対し、根拠に基づいた引用付きの回答（RAG）を返します	「Apple の 2024 年 10-K に記載された主なリスク要因は何ですか？」
get_filing_summary	提出書類全体の構造化されたエグゼクティブサマリー（事業、財務、MD&A、リスク、見通し）を作成します	「NVIDIA の最新の 10-K を要約して」
compare_companies	各社の提出書類を根拠として、特定の側面について 2～4 社を並べて比較します	「NVIDIA と AMD の AI チップ戦略を比較して」
detect_financial_anomalies	企業の MD&A／リスク開示における、前年比で注目すべき変化を検出します	「NVIDIA の中国に関するリスク表現は 2023 年から 2024 年にかけて変わりましたか？」
get_earnings_summary	四半期決算リリース（8-K）から主要指標、ガイダンス、経営陣のコメントを抽出します	「Apple の 2024 年第 2 四半期決算を要約して」

🛠️ 技術スタック

オープンソースと無料枠を優先しており、最初から最後まで実行するために有料 API は必要ありません。

レイヤー	ツール	理由
MCP プロトコル	mcp Python SDK	Anthropic 公式 SDK
SEC データ	SEC EDGAR Full-Text & Submissions API	公式、無料、API キー不要
埋め込み	sentence-transformers — intfloat/e5-base-v2	CPU で動作し、GPU は不要
ベクトルストア	Qdrant	無料のセルフホスト（Docker）または Qdrant Cloud
ローカルキャッシュ	DuckDB	ティッカー検索、提出書類のメタデータ、BM25 テキスト
キーワード検索	rank-bm25	高密度検索と組み合わせたハイブリッド検索
再ランキング	sentence-transformers CrossEncoder（ms-marco-MiniLM-L-6-v2）	LLM に渡す前に上位候補を再スコアリングします
HTML／PDF 解析	beautifulsoup4、pdfplumber	生の提出書類をテキストに整形します
LLM	Google Gemini（無料枠）	回答の生成
可観測性	LangFuse	トレーシング、スパン、忠実度スコア
評価	RAGAS	忠実度／正確性／再現率の自動スコアリング
テスト	pytest、pytest-asyncio	120 件以上のテストを完全にモックし、ネットワーク呼び出しなしで実行
リント	Ruff
CI/CD	GitHub Actions	すべての PR でリント、テスト、Docker ビルド、評価ゲートを実行
コンテナ化	Docker + Docker Compose
デプロイ	Oracle Cloud の「Always Free」枠	実際に永続化されるディスク、最大 24GB の RAM、$0
パッケージング	PyPI + uv/uvx、Hatchling	コマンド 1 つでインストールでき、クローンは不要

🏗️ アーキテクチャ

flowchart LR
    A[Claude Desktop / MCP client] -->|MCP tool calls| B[sec-intelligence-mcp server]
    B --> C[SEC EDGAR API]
    B --> D[Qdrant<br/>vector search]
    B --> E[Gemini<br/>answer generation]
    B --> F[LangFuse<br/>tracing + eval scores]
    C -->|filings| B
    D -->|cited passages| B
    E -->|grounded answer| B

📊 評価結果

RAGAS を使用し、5 社にわたる、手作業で検証した質問／正解ペア 50 件で測定しました（方法の詳細と生の結果は eval/README.md を参照してください）。

検索戦略	忠実度	正確性	コンテキスト再現率
v1：セマンティック検索のみ（高密度埋め込み）	0.92	0.67	0.84
v2：ハイブリッド（BM25 + RRF によるセマンティック検索）— 本番環境のデフォルト	0.95	0.78	0.99
v3：ハイブリッド + クロスエンコーダーによる再ランキング	0.98	0.82	1.00

CI の評価ゲートでは、これらの質問のうち実際にライブ取り込みしたサブセットで忠実度が 0.75 を下回ると、main への PR が失敗します。.github/workflows/ci.yml を参照してください。

LangFuse ダッシュボード

「NVIDIA は輸出規制によってどのようなリスクに直面していますか？」という質問に analyze_filing が回答した実際のトレースです。スパンツリーにはツール呼び出しの下に retrieval と embedding がネストされ、LLM の生成とともに表示されています。また、faithfulness: 1.00 のスコアが自動で付与されています。

---

👩‍💻 開発者向け

ソースから実行したり、コントリビュートしたり、公開パッケージを使わずにセルフホストしたりしますか？

Qdrant の起動

最も簡単な方法は Docker です。docker run -p 6333:6333 qdrant/qdrant を実行してください。Docker を使わない場合は、無料の Qdrant Cloud クラスターを使い、QDRANT_API_KEY も設定してください。

ローカルクローンから実行する

1. uv をインストールします。
2. リポジトリをクローンし、依存関係をインストールします。

   git clone https://github.com/jahanv01/sec-intelligence-mcp.git
   cd sec-intelligence-mcp
   uv sync
   

3. .env.example を .env にコピーし、上の表に記載されたキーを入力します。
4. Qdrant をローカルで起動します。

   docker compose up -d qdrant
   

5. サーバーを直接実行します。

   uv run python src/server.py
   

   または、MCP Inspector（開発用 UI。Node.js が必要）を使います。

   uv run mcp dev src/server.py
   

Claude Desktop では、公開パッケージの代わりにクローンしたリポジトリを指定します。

{
  "mcpServers": {
    "sec-intelligence-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\ABSOLUTE\\PATH\\TO\\sec-intelligence-mcp",
        "run",
        "python",
        "src/server.py"
      ]
    }
  }
}

必須のキーが不足している場合、src/config.py はインポート時に即座に失敗し（RuntimeError を発生させ）ます。

Docker で実行する

docker compose up -d を実行すると、サーバーイメージをビルドし、Qdrant とともに起動します。app サービスは env_file を介してローカルの .env からシークレットを読み込みます。また、コンテナ内の localhost からは qdrant コンテナにアクセスできないため、QDRANT_URL は http://qdrant:6333（ネットワーク内のサービス名）に上書きされます。

ローカルでのテスト

uv run python -c "import mcp"                    # SDK installed correctly
uv run python scripts/test_server_stdio.py        # server responds over stdio (ping -> pong)
docker compose up -d qdrant
uv run python scripts/test_qdrant.py               # Qdrant round-trip works

# EDGAR data layer (each hits the real EDGAR API)
uv run python scripts/test_edgar_lookup.py         # ticker -> CIK, DuckDB-cached
uv run python scripts/test_edgar_filings.py        # recent 10-K filings for a ticker
uv run python scripts/test_edgar_parser.py         # download + clean a real filing
uv run python scripts/test_edgar_sections.py       # section detection + metadata

# Embedding & retrieval pipeline (real model + real Qdrant)
uv run python scripts/test_chunker.py              # section/paragraph chunking
uv run python scripts/test_encoder.py              # E5 embedding shape/latency
uv run python scripts/test_ingest.py               # chunk -> embed -> upsert to Qdrant
uv run python scripts/test_search.py               # semantic search with citations

# MCP tools (real pipeline + real Gemini calls)
uv run python scripts/test_tool_ingest_company_filings.py
uv run python scripts/test_tool_search_filings.py
uv run python scripts/test_tool_analyze_filing.py
uv run python scripts/test_tool_get_filing_summary.py

# Full mocked suite (no network calls)
uv run pytest tests/ -m "not integration"

プロジェクト構成

src/
├── server.py         # MCP server entrypoint
├── tools/             # One file per MCP tool
├── edgar/             # SEC EDGAR fetching + parsing
├── embeddings/        # Chunking + embedding pipeline
├── retrieval/         # Qdrant client + search + hybrid + rerank
├── evaluation/         # RAGAS eval pipeline
└── config.py          # Env var loading (fail-fast)
tests/                  # Unit/integration tests
prompts/                # Prompt templates (.txt)
data/                   # Gitignored local cache (DuckDB, filing PDFs, Qdrant storage)
eval/                   # Test questions + ground truth answers
scripts/                # One-off dev/test scripts

独自のインスタンスをデプロイする

公開されている PyPI パッケージで、Claude Desktop を使った個人利用には十分です。スタンドアロンで一般公開されるサーバー（たとえば、リモート MCP クライアント向け）が必要な場合にのみ、以下の手順を使ってください。

Render や Hugging Face Spaces ではなく、Oracle Cloud の「Always Free」コンピュート VM（Ampere A1、ARM）にデプロイしています。これらのサービスではどちらも、コンテナのファイルシステムがエフェメラル（再起動や再デプロイのたびに消去）で、無料枠の RAM も 512MB に制限されており、埋め込みモデル（e5-base-v2、CPU のみ、ロード時に約 440MB）とプロセスの残りの部分を無理なく同時に実行できません。実際の Always Free VM にはそのような制約がなく、永続ディスクと最大 24GB の RAM を利用できるため、ローカル開発と同じ docker-compose.yml を使って Qdrant をローカルで実行でき、別途 Qdrant Cloud のアカウントを用意する必要もありません。

セットアップ（初回のみ）：

1. Oracle Cloud コンソールで Always Free Ampere A1 コンピュートインスタンス（Ubuntu イメージ）を作成し、パブリック IP を控えます。
2. VCN の Security List（インスタンス自体のファイアウォールだけでなく、両方で許可が必要です）に、TCP ポート 8000（および SSH 用の 22。通常はすでに開いています）のイングレスルールを追加します。
3. SSH で接続し、Docker と Compose プラグインをインストールしてから、次を実行します。

   git clone https://github.com/jahanv01/sec-intelligence-mcp.git
   cd sec-intelligence-mcp
   cp .env.example .env   # fill in GEMINI_API_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY
   echo "MCP_TRANSPORT=sse" >> .env
   sudo docker compose up -d --build
   

   この場合、.env に QDRANT_URL を設定する必要はありません。docker-compose.yml で、app サービス向けにネットワーク内のサービス名 http://qdrant:6333 へすでに上書きされています。
4. インスタンス自体のファイアウォールでもポートを開放します（Ubuntu には iptables／ufw のルールが標準で設定されており、Security List で許可してもポートがブロックされます）。

   sudo iptables -I INPUT -p tcp --dport 8000 -j ACCEPT
   sudo netfilter-persistent save   # or: sudo ufw allow 8000/tcp
   

5. curl http://<instance-public-ip>:8000/health を実行し、ok が返ることを確認します。

どちらのサービスにも restart: unless-stopped が設定されているため、VM が再起動すると、手動で操作しなくてもスタック全体が再び起動します。現時点ではプレーンな HTTP（TLS／ドメインなし）を使用しています。デモには問題ありませんが、実際の本番環境では Caddy または Nginx を前段に配置して HTTPS を有効にしてください。

代替案：Hugging Face Spaces。 Docker SDK を使って利用することもできます。この場合は、ローカルコンテナの代わりに Qdrant Cloud を使用します（Spaces のストレージは、実際の VM と異なり、再起動時にエフェメラルになります）。huggingface.co → New Space → SDK: Docker の順に進み、Space Settings で GEMINI_API_KEY、QDRANT_URL、QDRANT_API_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_PUBLIC_KEY を シークレット として、MCP_TRANSPORT=sse を 変数 として追加します。その後、このリポジトリを Space の git リモートに git push します。

🤝 貢献

Issue や PR を歓迎します。EDGAR API の仕様上の注意点（レート制限、必須の User-Agent ヘッダー）については docs/edgar-api.md を、検索パイプラインを変更する前には eval/README.md をご覧ください。RAGAS の忠実度を 0.75 未満に低下させる PR は、CI の eval-gate ジョブで失敗します。