Valuein MCP Server - US SEC Financial Data

Valuein — アナリスト、クオンツ、AI エージェント向けのSEC EDGARファンダメンタルデータ

ポイント・イン・タイムでサバイバーシップ・バイアスのないSECファンダメンタルデータ — AI エージェント向けに構築され、AIを懸念する機関投資家にも安心して使える設計です。 すべての数値は提出書類に基づき、fact_idを持ちます。モデルが数字を作り出すことはありません。Parquetでストリーミング配信し、DuckDBまたは自然言語でクエリできます。実行ごとに再現可能です。

このリポジトリは、Valueinデータプラットフォームの公開拠点および発見ハブです。ドキュメント、例、ノートブック、そしてAI エージェントがValueinを見つけるためのMCPレジストリマニフェストを掲載しています。SDK、MCPサーバー、データパイプラインのソースコードは専用のリポジトリにあります。ここはその入り口です。

pip install "valuein-sdk>=7.1.0" # data for code
# or add this URL to any MCP-capable AI client:
# https://mcp.valuein.biz/mcp     # data for agents

---

このリポジトリの内容

目的	移動先
トークンなしで30秒以内にSDKを試す	クイックスタート（30秒、トークン不要）
提供しているすべての配信チャネルを確認する	配信チャネル
料金と各プランで利用できる機能を確認する	プランとアクセス
AI エージェントを第一に考えている理由を知る	AI エージェント向けに構築
AI エージェントを接続する（Claude、Copilot、ChatGPT、Cursor…）	AI エージェント向けMCP
役割別にWorkspaceを設定する（アナリスト、PM、クオンツ、クリエイター）	docs/WORKSPACE_GUIDE.md
データモデルを読む	データモデル
役割別のクイックレシピを探す	役割別レシピ
Pythonのエンドツーエンドの例を実行する	examples/python/
インタラクティブなノートブックを実行する（Colab）	examples/notebooks/
方法論／SLA／コンプライアンスを読む	ドキュメント
データエラーを報告する、または機能をリクエストする	サポートとコミュニティ
例やノートブックを投稿する	CONTRIBUTING.md

---

データプロダクト

SEC EDGARから直接取得した、サバイバーシップバイアスのない、特定時点の米国企業の財務データです。

• 1993年以降にSECへ報告しているすべての米国上場企業 — 10-K、10-Q、8-K、20-F、40-F、および修正報告書が対象です。存続中の企業も上場廃止企業も含まれ、破産、合併、上場廃止のいずれも除外されません。
• 未加工のXBRLタグを標準のstandard_concept名に正規化し、重要な財務比率（FY＋TTM）も事前計算しています。対応付けられていないタグは削除せず、'Other'の下に公開します。
• Parquetテーブル — 財務データ、比率、指数構成銘柄、修正報告イベント、トータルリターン指数を含む価格履歴に加え、InstitutionalティアではスマートマネーとForm ADVアドバイザーのテーブルも利用できます。
• Cloudflare R2上のクラウドParquet — DuckDBでストリーミングできます。データベースのセットアップも、ローカルへのダウンロードも不要です。
• PIT対応 — すべてのファクトにfiling_dateとミリ秒精度のaccepted_atが付与されています。

件数はスナップショットごとに変動するため、このページには記載していません。最新の数値はリアルタイムでご確認ください。client.manifest()はスナップショットID、last_updated、およびご利用プランのテーブルを返します。curl -s https://data.valuein.biz/v1/sample/manifest.json | jq .schema_versionを実行すると、最新のスキーマバージョンを確認できます。https://data.valuein.biz/v1/plansでは、各プランの対象企業数と履歴期間を確認できます。docs/data_catalog.mdには、標準概念と比率が記載されています。

他との違い

特性	利用者にとっての意味
🕒 特定時点のデータ	filing_date <= trade_dateにより、先読みバイアスを排除します。accepted_atを使えば、同日シグナルを日中単位で判定できます。
⚖️ サバイバーシップバイアスなし	上場廃止、破産、買収された企業もすべてのスナップショットに残ります。バックテストでは、市場が当時見ていた対象企業群を確認できます。
📊 標準化された概念	未加工のXBRLタグ（fact.concept）と標準名（fact.standard_concept）の両方が、すべての行に含まれています。非公開の対応付けテーブルはありません。
🔍 公認会計士が検証したカタログ	すべてのstandard_conceptにreview_confidenceが付与されています。会計士が名称、財務諸表上の分類、ルールを承認すると1.0となり、その後は固定されます。パイプラインは新しい概念を追加するだけで、検証済みの概念を変更することはありません。暫定段階では0.7です。review_confidence >= 1.0で絞り込むと、アナリスト、クオンツ、AIモデルが合意し、学習に利用できるラベルを取得できます。
🚀 DuckDBネイティブ	httpfs経由で、リモートParquetに対するミリ秒単位の分析が可能です。データベースのプロビジョニングは不要です。
🔁 追記専用の修正報告	10-K/Aは新しい行として追加され、元の行は残ります。過去の任意の日付における、報告時点の表示を再構築できます。
🧾 測定・公開された精度	公開され、出典が明記された会計上の恒等式に照らして数理的一貫性を検証しています。CIのゲートで確認されており、DuckDBのコマンド1つでご自身でも再計算できます。現在の測定値はdocs/accuracy/baseline.jsonにあります。
🔐 1つのトークンですべてのチャネルに対応	同じBearerトークンで、SDK、MCP サーバー、一括データAPIを認証できます。

---

AI エージェント向けに構築

Valuein は MCP を最優先し、特定のエージェントに依存しません。同じ型付きツール群を Claude、Copilot、ChatGPT、Perplexity、Gemini、Grok、Cursor、または独自の LangGraph / CrewAI エージェントで利用できます。設計目標はシンプルです — モデルが数値を生み出すことはありません。数値はツールで生成され、出所情報付きの事実として渡されます。モデルに許されるのは、渡された数値をもとに文章を組み立てることだけです。

保証	適用方法
事実単位の系譜	ツールが返す数値にはすべて fact_id と出典となる提出書類が付与されます。verify_fact_lineage を使えば、任意の fact_id を1回の呼び出しで正確な SEC 提出書類の URL にたどれます。
先読みゼロ	すべての時系列ツールは as_of_date を受け取り、その日付時点の情報セットを再構築します。これは、バックテストにおいて Parquet レイヤーが適用するものと同じ PIT の規律です。
再現可能な実行	ツールは決定論的で冪等です。同じ入力なら同じ出力になります。ローリングウィンドウも、隠れた「最新」もありません。エージェントはキャッシュ、再試行、再生が可能で、後から実行を再現できます。
エージェントに依存しない状態	テーゼ、主張、ウォッチリスト、シグナル、レポートはセッション間、さらにはクライアント間でもサーバー側に保存されます。今日 Claude からテーゼを保存し、明日は Cursor から一覧表示できます。
Human-on-the-loop（HOTL）	状態を変更するツール操作や外部に影響するツール操作は、段階的アクションの承認台帳を経由します。エージェントが提案し、人間が承認すると、その判断が変更不可能な監査記録に記録されます。読み取り専用ツールでは段階的アクションは発生しません。
ガバナンスされたマネージド実行	サーバー側のマネージドエージェント実行は、温度 0、モデル許可リスト、破壊的なツールの除外を適用します。即興ではなく、再現可能な調査を実現します。
評価付きの実績記録	保存されたテーゼと主張は、その後のファンダメンタルズや価格と照合してスコア化されます。公開すると、検証可能な公開実績記録が作成され、エージェントがスコアを管理します。

ツールの完全なリファレンスは docs/MCP_TOOLS.md に、エージェント向けの実行時の指示は AGENTS.md にあります。

---

提供チャネル

同じデータセットを4つの方法で提供するため、普段使っている場所で利用できます。

チャネル	対象	エンドポイント／インストール
Python SDK	クオンツ、エンジニア、データサイエンティスト	pip install valuein-sdk · PyPI
MCP サーバー	AI エージェント（Claude、Copilot、ChatGPT、Cursor、カスタム）	https://mcp.valuein.biz/mcp · server.json
ウェブダッシュボード	個人投資家、経営幹部、技術者以外のユーザー	valuein.biz
一括データ API	B2B パートナー、フィンテックプラットフォーム	https://data.valuein.biz · お問い合わせ

Stripe 発行の単一トークンで、利用プランに応じてすべてのチャネルを利用できます。チャネルごとの課金はありません。

---

プランとアクセス

料金と機能範囲はこちらの内容が反映されています。ウェブサイトが正確な情報源であり、チェックアウトのフローでは適切な Stripe 製品に誘導されます。

プラン	対象範囲	履歴	利用方法
Sample	米国大型株ベンチマークの対象銘柄群	直近数年	無料、登録不要：pip install "valuein-sdk>=7.1.0"
Benchmark	米国大型株ベンチマークの対象銘柄群	全期間	無料、登録
Pro	米国の現行銘柄および上場廃止銘柄の全対象銘柄群、ファンダメンタルズデータセット	ローリング方式の時点データ期間	サブスクリプションに登録
Institutional	同じ対象銘柄群 + スマートマネーデータセット（Form 3/4/5/144 のインサイダー取引 + Form 13F/13D/13G の機関投資家保有状況）	1993年まで遡る全期間	サブスクリプションに登録
Enterprise	個別交渉 · 専用インフラストラクチャ · 拡張された再配布範囲	カスタム	[email protected]

価格、対象銘柄数、履歴期間、レート制限はリアルタイムで提供されます。コピーではなく、以下から読み取ってください。

curl -s https://data.valuein.biz/v1/plans \
  | jq '.plans[] | {displayName, priceUsd, universeSize, earliestYear, perMinute, perHour}'

各プランは異なる購入時の懸念を解消します。Pro ではファンダメンタルズデータセットの対象銘柄数と履歴の制限がなくなります。Institutional ではスマートマネーデータセット（インサイダー取引 + 機関投資家保有状況）、1993年まで遡る無制限の履歴、提出イベントの Webhook、営業時間内の SLA に基づく商用再配布ライセンスが追加されます。Enterprise では専用インフラストラクチャと個別契約が追加されます。

従量課金（MPP）

レート制限やプランの上限に達した自律型AIエージェントは、Stripe のカードトークンを使ってリクエストごとに支払えます。人間によるチェックアウトは不要です。支払いには Machine Payment Protocol を使用します。エージェントが料金を照会し、カードの Shared Payment Token に課金してから、確認済みのトークンを使って MCP 呼び出しを再試行します。

現在、支払い方法はカードのみです。 支払いの前に https://api.valuein.biz/api/mpp/well-known を取得し、利用可能なネットワークを確認してください。

カテゴリ	例	課金単位
プロベナンス／スキーマ	describe_schema、verify_fact_lineage	無料
検索	search_companies、get_sec_filing_links	エンティティごと
ファンダメンタルズ	get_company_fundamentals、get_financial_ratios	エンティティごと
分析	get_valuation_metrics、get_peer_comparables、compare_periods、get_capital_allocation_profile	エンティティごと
計算	compute_dcf、forensic_audit、generate_dcf_xlsx、generate_research_brief_docx、generate_comps_xlsx	呼び出しごと
スクリーニング／ユニバース	screen_universe、get_pit_universe	呼び出しごと
スマートマネー（機関投資家データセット）	get_insider_transactions、get_insider_sentiment、get_institutional_holdings、get_manager_portfolio、get_blockholders、get_top_holders、get_smart_money_flow	エンティティごと

最新の料金：curl -s https://data.valuein.biz/v1/plans | jq '.paygRates, .toolToMeter'（各ツールの課金先メーターと米ドル建て料金）。402 は、承認の前に正確な料金を提示します。従量課金は、呼び出しごとの料金がサブスクリプションより高いため、エージェントを継続的に利用する場合は、ほとんどの場合Pro または Institutional サブスクリプションのほうがお得です。MPP の3ステップのフロー全体については、AGENTS.md をご覧ください。

「エージェントが安全に自分のデータを購入する」という一連の仕組みは、リファレンス実装として docs/AGENT_ECONOMY_RAIL.md にまとめられています。2種類の同意モデル（人間が承認した上限付き予算で自動課金し、インラインで提供する方法、またはウォレットを持つエージェント向けの呼び出しごとの MPP）、これが安全なデフォルトである理由、そしてレールを検出して無料で最新の料金を読み取る、実行可能なデモ examples/python/agent_buys_its_own_data.py を紹介しています。

プランごとのレート制限は、https://data.valuein.biz/v1/plans の perMinute／perHour フィールドです（プランとアクセスにある jq コマンドで確認できます）。

---

クイックスタート（30秒、トークン不要）

すでに使っている Python のワークフローを選んでください。どちらも任意の仮想環境で動作し、以下と同じコードを実行します。

# Option A — pip (universal, ships with Python)
python -m venv .venv && source .venv/bin/activate
pip install "valuein-sdk>=7.1.0"

# Option B — uv (10–100× faster; install from https://docs.astral.sh/uv/)
uv venv && source .venv/bin/activate
uv pip install "valuein-sdk>=7.1.0"

手間いらずを前提に設計されています。 VALUEIN_API_KEY がなくても問題ありません。SDK はトークンがないことを検出し、SAMPLE データセット（S&P 500、過去5年分）にフォールバックします。エッジゲートウェイも同様です。Authorization ヘッダーなしで GET /v1/{sp500,pro,full}/:table にアクセスすると、自動的に /v1/sample/:table へ 302 リダイレクトされます。以下のスニペットは、そのまま実行できます。

from valuein_sdk import ValueinClient

with ValueinClient() as client:
    print(client.me())               # {plan, status, email, createdAt}
    print(client.manifest())         # snapshot id, last_updated, tables
    print(client.tables())           # tables your plan can read (they load on first use)

    df = client.run_query("""
        SELECT r.symbol, r.name, r.sector
        FROM   "references" r
        JOIN   index_membership im ON im.cik = r.cik
        WHERE  im.index_name = 'SP500'
          AND  im.removal_date IS NULL
          AND  r.is_active = TRUE
        ORDER  BY r.name
        LIMIT  10
    """)
    print(df)

これはライブの S&P 500 サンプルに対する実際のクエリです。全ユニバースまたは全履歴が必要な場合にのみ、トークンを追加してください。

# optional — the sample tier works without a key
export VALUEIN_API_KEY="your_token_here"      # or add this line to a .env file

同じコードで、ご利用のプランのデータを読み込めるようになります。それ以外の変更は不要です。ValueinClient() は、環境変数から VALUEIN_API_KEY を読み取るか、作業ディレクトリから上位へたどって最初に見つかった .env から読み取ります。ValueinClient(api_key="") を指定すると、環境変数の値にかかわらず、無料のサンプルを強制的に使用します。このリポジトリの curl と DuckDB の例では、同じトークンを $VALUEIN_TOKEN に保持します。これはシェル変数名が異なるだけで同じトークンであり、SDK はこの変数を読み取りません。

本番環境向けのパターン — コンテキストマネージャー、型付きエラー、事前構築済みテンプレート

from valuein_sdk import (
    ValueinClient,
    ValueinAuthError,
    ValueinPlanError,
    ValueinRateLimitError,
    ValueinAPIError,
    ValueinError,
)

# Two-level try/except is intentional:
#   outer = init errors raised by ValueinClient.__enter__ (auth, manifest, 503)
#   inner = per-query errors raised by run_query / run_template (rate-limit,
#           plan denial, bad SQL). Each level dispatches by exception type so
#           you can act on the right cause — exit on auth, sleep on rate-limit,
#           upsell on plan, log + skip on a single bad row.

try:
    with ValueinClient() as client:
        try:
            # 1) Build & run a raw SQL query → pandas DataFrame
            sql = "SELECT COUNT(cik) FROM entity"
            result = client.run_query(sql)
            print(result)

            # 2) Run a named SQL template with kwargs (the SDK quotes safely)
            df = client.run_template(
                "fundamentals_by_ticker",
                ticker="AAPL",
                start_date="2020-01-01",
                end_date="2024-12-31",
                form_types=["10-K", "10-Q"],
                metrics=["TotalRevenue", "NetIncome", "OperatingCashFlow"],
            )
            print(df.head())
        except ValueinPlanError:
            print("This query needs a higher plan — see valuein.biz/pricing.")
        except ValueinRateLimitError as e:
            print(f"Rate limited; retry in {e.retry_after}s.")
        except ValueinError as ve:
            # Catch-all for any other per-query failure (validation, bad SQL, etc.)
            print(f"Query failed: {ve}")
except ValueinAuthError:
    raise SystemExit("Token missing or expired — set VALUEIN_API_KEY.")
except ValueinAPIError as e:
    print(f"Gateway error during init (HTTP {e.status_code}).")
except Exception as e:
    print(f"Initialization failed: {e}")

SDK には、一般的なスクリーニング、比率、PIT バックテスト向けの名前付き SQL テンプレートが含まれています。インストール済みのバージョンに含まれるテンプレートを一覧表示するには、次のようにします。

from valuein_sdk import ValueinClient
with ValueinClient() as c:
    print(c.list_templates())

数値のすべてを提出書類まで追跡できる財務諸表とスクリーニング

from valuein_sdk import ValueinClient

with ValueinClient() as client:  # no token: free sample tier
    fin = client.financials("AAPL")  # income, balance sheet, cash flow as known at as_of
    print(fin.income)
    print(fin.lineage.head())  # each number's fact_id, filing accession and acceptance time

    screen = client.screen("2024-06-28", universe="SP500").where("return_on_equity > 0.15")
    print(screen.top(10, by="gpoa").to_pandas().summary())  # members on that date, delisted included

主な操作

したいこと	呼び出し	プラン
時点ビューに対する生の SQL	client.run_query(sql)、client.duckdb()	すべて
ある日に把握されていた財務諸表	client.financials("AAPL", freq="FY")（"Q"、"TTM"；.as_filed()）	すべて
過去の日付における指数構成銘柄（上場廃止銘柄を含む）	client.universe(dates=[...])、client.pit_universe("2022-06-30")	すべて
それらの日付時点で把握されていた比率	client.signal_panel(members, ratios=[...], include_price=False)	すべて
時点スクリーニング	client.screen("2024-06-28").where("return_on_equity > 0.15")	すべて（価格フィールド：Pro）
2段階 DCF（入力値のトレース付き）	client.dcf("MSFT", stage1_growth_rate=0.08)	すべて
同業他社と修正再表示	client.peers("MSFT", n=5)、client.restatements(ticker="MPWR")	すべて
分位バックテスト、データの各版、試行回数のカウント	client.factor_backtest(...)、client.restatement_impact(...)、client.study(...)	日次バー：Pro および Institutional
データのミラーリングまたは固定	client.sync(path)、ValueinClient.from_bundle(path)	プランによる制限あり

from valuein_sdk import ValueinClient

client = ValueinClient()  # reads VALUEIN_API_KEY; no key = free sample

# S&P 500 members on a past date, later-removed companies included
members = client.universe(dates=["2022-06-30"])

# Return on equity as it was known on that date
panel = client.signal_panel(members, ratios=["return_on_equity"], include_price=False)
print(panel.head())

# A DCF with your growth assumption; every input traced to its filing
dcf = client.dcf("MSFT", stage1_growth_rate=0.08)
print(dcf.value_per_share, dcf.price, dcf.upside)

# Numbers a later filing changed, with both filings
print(client.restatements(ticker="MPWR").head())

同じクライアントで、ティアシート付きのファクターバックテスト、時点・提出時点・修正再表示後の数値によるファクター比較、試行回数のカウント（ディフレート済みシャープレシオ）、データスナップショットのミラーリングや固定を実行できます：docs/SDK_USE_CASES.md。

リファレンス：docs/QUERY_COOKBOOK.md（DuckDB のレシピ） · docs/data_catalog.md（標準的な概念） · PyPI README（SDK のクイックスタート）。

---

役割別レシピ

以下のリンクはすべて、examples/python/ にある実行可能なスクリプトを指しています。ほとんどのスクリプトには、examples/notebooks/ に対応するノートブックがあります。Sample ティアでは、Institutional のスマートマネー・スクリーニングを除くすべての例を、トークンも登録も不要で実行できます。

あなたの役割	まず試すもの	内容
財務アナリスト	financial_analysis.py	1つの銘柄から、売上高の推移、利益率の変化、同業他社との比較を確認します
クオンツ／研究者	factor_backtest.py	コストと IC を含む、時点ベースで生存者バイアスのない分位バックテスト
ポートフォリオマネージャー	entity_screening.py	過去の日付時点の S&P 500 をスクリーニングし、その後に除外された構成銘柄も含めて確認します
フォレンジックアナリスト	restatement_radar.py	修正再表示されたすべての数値、開示方法、検証用の両方の提出書類
資産運用会社	survivorship_bias.py	生存者バイアスによるリターンの過大評価を定量化します
バリュエーションモデル作成者	dcf_inputs.py	client.dcf()：独自の前提を使う2段階 DCF。すべての入力値の提出書類を追跡できます
監査／コンプライアンス担当者	filing_provenance.py	提出書類ごとの SEC EDGAR へのクリック可能なリンク。数値の根拠となる正確な原資料を iXBRL ビューアーで開けます
データエンジニア	production_service.py	Parquet へのスケジュールされた時点データ抽出：制限、ログ記録、終了コード
初めてのユーザー	getting_started.py	プランの確認、銘柄コードから CIK への変換、初めてのファンダメンタルズクエリ
AI エージェントを構築する方	MCP for AI agents	自然言語で利用できます。SDK は不要です

いずれも次のように実行できます：

# Sample tier — works without a token
python examples/python/getting_started.py

# Paid tier
VALUEIN_API_KEY=xxx python examples/python/factor_backtest.py

---

データモデル

完全なスキーマは、機械可読形式のdocs/schema.jsonと、正規の概念名を記載したdocs/data_catalog.mdにあります。すべてのプランで、以下のコアテーブル（時点ごとのSIC分類を含むindustry_classificationを含む）を読み取ります。有料プランではfiling_registrantも読み取ります。Institutionalプランでは、スマートマネー関連のテーブル（insider_party / insider_filing / insider_transaction / insider_ownership / insider_footnote / insider_ownership_purpose / institutional_filing / institutional_holding / institutional_other_manager）と、Form ADVのアドバイザーテーブル（investment_adviser、investment_adviser_private_fund）が追加されます。client.tables()でご利用のプランが読み取るテーブルを確認できます。curl -s https://data.valuein.biz/v1/sample/manifest.json | jq .schema_versionを実行すると、最新のスキーマバージョンが表示されます。

テーブル	内容	重要な理由
references	まずはこちらをご覧ください。 entity と security をフラットに結合したテーブルです。証券ごとに1行で、cik、is_active、セクター、取引所、FIGIを含みます。構成銘柄を調べるには、cik = cik で index_membership をJOINします。	企業横断のメタデータを1回のスキャンで取得できます。インデックスの構成銘柄情報は、過去の採用・除外履歴を保持するため、専用のテーブルに格納されています。
entity	企業のメタデータ — CIK、名称、セクター、SIC、ステータス、会計年度末	法的事業体のディメンションです。
security	ティッカーの履歴（valid_from / valid_to によるSCD Type 2）	過去のティッカー、株式クラス、取引所を特定できます。
filing	提出書類のメタデータ — accession_id、filing_date、report_date、フォームの種類、訂正フラグ	「いつ何が提出されたか」を表すディメンションです。
fact	標準化された財務ファクト — 各行に元の concept と正規化された standard_concept の両方を格納	財務数値です。accepted_at によりPITセーフです。
filing_registrant	accessionの各登録者（有料プランのみ。無料サンプルのマニフェストには含まれません）	filing は accession_id ごとに1行を保持するため、共同登録者による提出書類は1つのCIKにしか表示されません。accession_id で filing_registrant と filing を結合すると、共同提出分を含む企業の提出書類を一覧できます。
ratio	提出書類ごとにパイプラインで計算された財務比率	SQLを省略できます。利益率、リターン、レバレッジ、効率性を事前計算済みです。
taxonomy_guide	米国GAAPタクソノミーガイド	すべての standard_concept の定義です。
index_membership	cik をキーとするインデックス構成銘柄。effective_date / removal_date による半開区間を使用します。SP500は1996年まで遡ってサバイバーシップバイアスを排除しています（confidence='high'）。長期間前に上場廃止となった登録者を含む、実際の採用・除外期間を記録しています。RUSSELL1000 / RUSSELL2000 / RUSSELL3000は2000-09-30まで遡ります（confidence='medium'、source='fund_holdings'）。各インデックスに連動する大規模ファンドが公開したポートフォリオ保有銘柄から再構成しているため、ファンドはインデックスを定義するのではなく、その代理となります。また、採用日や除外日は観測間隔の精度に限られます（2006年までは年におよそ1～4回、2007年以降は毎月）。インデックスプロバイダーが公開するリバランス対象銘柄リストと照合して評価しています。これらのリストは評価にのみ使用し、再配布はしません。**再現率は96.5～98.3％、適合率は93.6～98.6％**です。2000-09-30より前のRussellデータはなく、2016-12-30から2017-07-31までの保有銘柄観測データもありません。	過去の日付時点でS&P 500またはRussellインデックスを再構成できます。confidence に基づいて分岐してください。medium は概算であり、権威あるデータではありません。企業のメタデータは references.cik = index_membership.cik でJOINします。
industry_classification	PIT対応のSEC SIC分類です。企業とSICの適用期間ごとに1行で、4桁の sic_code（サブ業種）、sic_industry_group、sic_major_group、sic_division、sector、industry を含みます。valid_from は、該当コードが初めて記載された提出書類のSEC受理時刻です。valid_to は排他的で、NULLは現在を表します。各提出書類のSECヘッダーに記載されたSICに基づいています。すべてのプランで利用でき、references と同じ企業が対象です。GICSはライセンス対象のため含まれません。公開されている最も細かい分類は4桁のSICです。	references.sector / industry / sic_code は現在の値で、過去のすべての期間にも適用されています。「日付t時点でこの企業はどの業種だったか」を調べるには、valid_from <= t AND (valid_to IS NULL OR t < valid_to) で絞り込んでください。企業について最初の情報が確認できる時点より前の行はありません。
standard_concept	正規化されたコンセプトのカタログ本体 — 名称、財務諸表、マッピング規則、公認会計士によるレビュー状況	fact.standard_concept の基準となるデータです。
stock_price	企業ごとの粗粒度な価格系列 — 会計期間末と月末ごとに終値を1つ記録し、すべての行に total_return_index を含みます（すべてのプランで利用可能）。	あらゆるプランで、バリュエーションと株価の比較や、月次リバランスのバックテストに利用できます。月末の2行間の tri_b / tri_a - 1 は、その期間における保有者のトータルリターンで、配当を含みます。
insider_footnote · insider_ownership_purpose · institutional_other_manager	Institutional限定 — Form 3/4/5の脚注（10b5-1プランや加重平均価格の根拠となる記述）、Schedule 13DのItem 4「取引の目的」の原文、13Fの運用者一覧	取引、持分、共同13Fの背景にあるテキストです。accession_id で insider_footnote と insider_ownership_purpose を insider_filing に、institutional_other_manager を institutional_filing に結合します。
stock_price_daily	InstitutionalおよびPro限定 — 上場銘柄ごとの全日次OHLCVバー系列。total_return_index と、未加工のコーポレートアクション係数（div_cash、split_factor）を含みます。	バックテストに安全な価格データです。ファンダメンタルズと組み合わせて、PIT対応のバリュエーション倍率を計算できます。トータルリターンには total_return_index を使用してください。これは前向きに複利計算されるため、バックアジャスト済み系列とは異なり、後日の株式分割によって過去の値が改訂されることはありません。adjusted_close はベンダーからそのまま渡された値で、大半のバーではnullです。粒度は証券ごと、日ごとに1行です。企業ごとに1行にするには WHERE is_primary_listing を追加してください。価格データはライセンス対象の市場データであり、EDGARデータではないため、ファンダメンタルズデータの1993年開始という下限は適用されません。1993年のバーはなく、最も古いバーは証券ごとに異なり、1994年以降です。

Parquet ファイルを直接読み込む

テーブルは HTTPS 経由のプレーンな Parquet ファイルです。無料サンプルではトークンもファイル拡張子も不要です。有料プランでは Bearer トークンを送信します。有料ルートにトークンなしでリクエストすると、サンプルのコピーにリダイレクト（302）されます。

# Free sample — no token, no card
curl -sL https://data.valuein.biz/v1/sample/entity -o entity.parquet

# Paid tiers: sp500 | pro | full — the same Bearer token as the SDK, kept here in $VALUEIN_TOKEN
curl -sL -H "Authorization: Bearer $VALUEIN_TOKEN" https://data.valuein.biz/v1/pro/references -o references.parquet

# One company's partition of a large table (10-digit CIK)
curl -sL -H "Authorization: Bearer $VALUEIN_TOKEN" https://data.valuein.biz/v1/pro/fact/0000320193.parquet -o aapl_fact.parquet

https://data.valuein.biz/v1/sample/manifest.json には、サンプルのテーブルとスキーマバージョンが記載されています。

日付列 — 用途に応じた選び方

列	テーブル	用途
report_date / period_end	filing / fact	会計年度カレンダーとの照合
filing_date	filing	PIT バックテストのフィルター — SEC が受理した日付
accepted_at	fact、filing、ratio（およびスマートマネーと価格のテーブル）	日中の調査におけるミリ秒精度の PIT

複数企業を対象とするバックテストでは、必ず filing_date <= trade_date でフィルターしてください。report_date でフィルターすると、先読みバイアスが生じます。

DuckDB で効果を発揮する 3 つのパターン

1. references から始める（複数企業のフィルターには結合が 1 回必要です。メンバーシップは index_membership にあります）：

SELECT r.symbol, r.name, r.sector
FROM   "references" r
JOIN   index_membership im ON im.cik = r.cik
WHERE  im.index_name = 'SP500'
  AND  im.removal_date IS NULL          -- current member
  AND  r.is_active     = TRUE
  AND  r.sector ILIKE '%technology%'

2. 企業ごとの最新の提出書類には LATERAL を使う（抜粋：r を定義するパターン 1 のクエリに、この結合を追加してください）：

JOIN LATERAL (
    SELECT accession_id, filing_date FROM filing
    WHERE  entity_id = r.cik AND form_type = '10-K'
    ORDER  BY filing_date DESC LIMIT 1
) f ON TRUE

3. 1 回の fact スキャンで複数の概念をピボットする：

SELECT
    MAX(CASE WHEN standard_concept = 'TotalRevenue'       THEN numeric_value END) AS revenue,
    MAX(CASE WHEN standard_concept = 'StockholdersEquity' THEN numeric_value END) AS equity
FROM   fact
WHERE  standard_concept IN ('TotalRevenue', 'StockholdersEquity')
GROUP  BY accession_id

四半期キャッシュフローには、COALESCE(derived_quarterly_value, numeric_value) を使用してください。Q2/Q3 の 10-Q では年初来の数値が報告されるため、この列で単一四半期の数値を切り出します。CAPEX の符号は提出者によって異なるため、必ず ABS(capex) を使用してください。

レシピ、アンチパターン、エンドツーエンドのファクタースクリーニングを含むクックブック全文は、docs/QUERY_COOKBOOK.md にあります。

正規概念名

fact.standard_concept では、'TotalRevenue'、'NetIncome'、'OperatingCashFlow'、'CAPEX'、'StockholdersEquity' などの正規名をクエリしてください。生の XBRL タグ（'Revenues'、'NetIncomeLoss'、'Assets'）は使用しないでください。全一覧は docs/data_catalog.md にあり、機械可読形式は docs/data_catalog.json にあります。

---

AI エージェント向け MCP

Valuein は、プロトコルネイティブなリモートの Model Context Protocol サーバーを提供します。これにより、MCP 対応エージェント（Claude、Copilot、ChatGPT、Cursor、カスタムエージェント）が、コードを書かずにファンダメンタルズに関する質問に回答し、永続的で監査可能な調査状態を維持できます。

• エンドポイント： https://mcp.valuein.biz/mcp（Streamable HTTP、MCP spec 2025-11-25）
• 認証： Authorization: Bearer <your_api_token> — SDK および一括データ API と同じトークンです
• マニフェスト： server.json — registry.modelcontextprotocol.io に io.github.valuein/mcp-sec-edgar として公開されています
• リファレンス： docs/MCP_TOOLS.md — 各ツール、各入力、各ティアの制限、エラーとページ分割された結果の読み方を記載しています（ライブマニフェストから生成）

ツール

サーバーは、127 個の稼働中ツールに加え、39 個のエージェント型 SOP プロンプト（主要なペルソナ横断ブリーフ 2 種 — equity_research_brief と screen_and_shortlist — およびアナリスト、PM、クオンツ、比率、スマートマネー、ワークフローの各ペルソナ向けの専門チェーン）と、3 個のデータリソース（schema://{table}、reference://sp500、pricing://current）を提供します。ティア制限はデータレイヤーで適用されます。Sample / Benchmark トークンでは Sample / Benchmark の範囲（S&P 500 構成銘柄）を利用でき、Pro では 15 年間のポイントインタイム期間（2011 年から現在まで）を含む 19,000 を超える事業体の全ユニバースを利用できます。Institutional では、スマートマネーツール（Form 3 / 4 / 5 / 144 のインサイダー取引および Form 13F / 13D / 13G の機関投資家保有状況）、1993 年まで遡る無制限の履歴、提出イベントの Webhook、商用再配布ライセンスが利用可能になります。

ディスカバリーとスキーマ

ツール	機能
search_companies	ティッカー、企業名、CIK を検索し、セクター、S&P 500、現役状況で絞り込みます
describe_schema	任意のテーブルの列、型、説明を返します
get_pit_universe	任意の過去の as_of_date における、サバイバーシップバイアスのないメンバーシップ（S&P 500、Russell 1000 / 2000 / 3000、セクター、または全ユニバース）をページ分割して返します
基礎指標と比率

ツール	内容
get_company_fundamentals	ティッカーと期間ごとの損益計算書、貸借対照表、キャッシュフロー
get_financial_ratios	利益率、リターン、レバレッジ、効率性、FCF利回り（カテゴリー別）
get_valuation_metrics	企業の取引価格と、パラメーター不要の参考指標。内在価値は、指定した前提条件を使って compute_dcf で算出します
get_capital_allocation_profile	設備投資の強度、自社株買い利回り、配当履歴

提出書類とデータの系譜

ツール	内容
get_sec_filing_links	10-K / 10-Q / 8-K / 20-F / 40-F のEDGAR直リンク
verify_fact_lineage	任意の数値を、その出典である正確な提出書類とアクセッションIDまで追跡

比較と分析

ツール	内容
compare_periods	重要な変化のフラグ付きで期間を横並び比較
get_peer_comparables	セクター別の同業企業グループと比較指標
screen_universe	全銘柄を対象とする多要素スクリーニング

一括データ

ツール	内容
get_compute_ready_stream	署名付きの有効期限付きダウンロードURLを発行し、ゲートウェイを経由せずにParquetを直接ストリーミング

スマートマネー — Institutionalティア以上

スマートマネーバンドルは、Bloombergの INSIDER<GO> / OWNER<GO> / HDS<GO> スクリーンを単一のValueinトークンに置き換えます。各ツールはCIKごとのParquetパーティションを読み込み、ワンクリックでSEC検証できる lineage エンベロープ付きの構造化行を返します。

ツール	内容
get_insider_transactions	発行体ごとのForm 3 / 4 / 5 / 144の明細。名前と役職についてinsider_partyと結合
get_institutional_holdings	1つの発行体におけるForm 13Fの上位保有者を、HHI集中度と13F遅延の古さフラグ付きで取得
get_manager_portfolio	Form 13F提出者の全ポートフォリオと、前四半期比の変化（新規／増加／減少／売却）
get_blockholders	一級の going_active フラグを備えたSC 13D / 13G（13G→13Dは支配権変更のシグナル）
get_insider_sentiment · get_top_holders · get_smart_money_flow	発行体ごとのインサイダーの買い／売りシグナル集計、最大保有者、機関投資家の純フロー

永続的でエージェントに依存しない調査状態（すべてのMCPクライアント）

調査オブジェクトはサーバー側に保存され、トークンにひも付けられます。あるAIクライアントから保存し、別のクライアントから読み取り、後でスコアを付けられます。

ファミリー	ツール（代表例）	内容
テーゼと主張	save_thesis、save_claim、score_thesis_outcome、score_claim	出典にひも付いた主張を含むタイムスタンプ付きの見解。後続のファンダメンタルズと株価に基づいて自動採点
ウォッチリストとシグナル	save_watchlist、create_signal、list_signal_inbox	株価の動き、ファンダメンタルズの変化、提出書類を継続監視し、メール、Webhook、ダッシュボードの受信トレイ、または常駐エージェントチームを起動する agent_run に配信
レポート	create_report、render_report、save_freeform_report	ブランド付きmd/docxエクスポートに対応した、永続的でバージョン管理された調査成果物
延期とルール	schedule_task、create_rule、test_rule	「30日後にAAPLの利益率を再確認」→実際にスケジュールされた再実行。トリガー→アクションのルール（シグナル発火、受信トレイ項目、タスク起動、スケジュールの時刻到来）
承認（HOTL）	stage_action、list_pending_approvals、approve_staged_action	変更を伴う操作や破壊的な操作は人間の承認待ちとして登録され、改変不能な監査記録が作成されます
バックテスト	run_backtest、get_pit_valuation_ratios、get_price_history	任意の過去時点を対象とする、範囲制限付きのPITファクターグリッドとバックテスト対応のバリュエーション倍率
ブリーフィング	get_morning_brief、list_agent_runs	任意のMCPクライアントから、日次ブリーフと管理対象の実行履歴を確認

公開 — 無料で評判を構築（サインイン済みのすべてのプラン） 保存した調査を公開 @handle プロフィールで公開できます。公開実績と評判を無料で築けます。レポートは共有可能な /r/[slug] ページになり、キーワードカタログ検索で見つけられるようになります（セマンティック検索にはまだ対応していません）。論文と主張にも、同じ無料の publish ／ unpublish 公開設定切り替えが適用されます。これは公開であり、販売ではありません。

ツール	機能
publish_report	保存済みレポートを公開プロフィール（@handle）で、共有可能な /r/[slug] ページとして公開します
unpublish_report	以前に公開したレポートを再び非公開にします
search_reports	ティッカー、作成者、キーワードで公開レポートカタログを検索します（キーワードカタログ検索）
publish_thesis / unpublish_thesis	保存済みの論文をプロフィールで公開／非公開に切り替えます — publish_report と同等の機能です
publish_claim / unpublish_claim	保存済みの主張をプロフィールで公開／非公開に切り替えます — publish_report と同等の機能です

Claude Desktop での設定

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "valuein": {
      "url": "https://mcp.valuein.biz/mcp",
      "headers": { "Authorization": "Bearer YOUR_VALUEIN_API_KEY" }
    }
  }
}

同じ URL と Bearer トークンは、Streamable HTTP リモートに対応するすべての MCP クライアントで使えます。Copilot、ChatGPT、Cursor、独自の LangGraph ／ CrewAI エージェントなどが対象です。

---

このリポジトリのサンプル

すべてのスクリプトとノートブックは、PyPI で公開されている SDK を使用します。Sample ティアはトークンなしで実行できます。有料ティアを使うには VALUEIN_API_KEY を追加してください。

各項目の対象者と必要なプランを含む、学習パスの全体については、examples/README.md をご覧ください。

Python スクリプト（examples/python/）

スクリプト	レベル	内容
getting_started.py	初級	プラン、スナップショット、ティッカー → CIK、年間売上高と純利益
financial_analysis.py	初級	損益計算書と利益率、四半期単独のキャッシュフロー、同業他社の比率
pit_backtest.py	中級	同じクエリでも as_of の日付を変えると異なる結果が得られる例（実際の修正再表示）
entity_screening.py	中級	過去の日付時点の S&P 500 をスクリーニング
survivorship_bias.py	中級	バイアスを含まない等ウェイトリターンと、生存銘柄のみの等ウェイトリターンの比較
factor_backtest.py	上級	ユニバース → シグナル → 将来リターン → コスト込みの分位バックテスト
pit_factor_dataset.py	上級	ポイント・イン・タイムかつサバイバーシップバイアスのないファクターファイルを Parquet と CSV に出力
price_total_return.py	中級	株式分割と配当がリターンに与える影響。Pro では日次ヘルパーも利用可能
restatement_radar.py	中級	開示内容の構成、検証済みの改訂例 1 件、最近の Item 4.02 改訂
smart_money_screen.py	中級	インサイダー取引、13F 保有者、大口保有者（Institutional）
filing_provenance.py	初級	数値、再計算した fact_id、SEC 提出書類へのリンク
dcf_inputs.py	中級	入力値の追跡、1 株あたり価値、含意される成長率を示す client.dcf()
production_service.py	上級	制限、ログ、終了コードに対応した、スケジュール実行のポイント・イン・タイム抽出から Parquet への出力
agent_buys_its_own_data.py	上級	エージェントが決済手段を見つけ、リアルタイムの価格見積もりを取得

Jupyter ノートブック（examples/notebooks/）

無料の sample ティアで実行し、出力を含めてコミットしています。

ノートブック	Colab で開く
クイックスタート
特定日時点のファンダメンタルズ
サバイバーシップバイアスのないスクリーニング
時点整合型ファクターバックテスト
株価とトータルリターン
修正再表示
スマートマネー（機関投資家）
数値を検証する
AI アシスタントから利用する
DCF バリュエーション
ピオトロスキー F スコアによるスクリーニング
利益の質
セクター比較
修正再表示アルファ
資本配分
提出遅延

---

ドキュメント

docs/ 内のすべての内容は、本番データおよびPyPI上のSDKと同期されています。

ドキュメント	内容
docs/WORKSPACE_GUIDE.md	ワークスペースのウェルカムガイド — 15分でできるセットアップと、役割別（アナリスト、PM、クオンツ、クリエイター）の日次／週次／月次プレイブック
docs/METHODOLOGY.md	データソース、PITアーキテクチャ、修正再表示への対応、XBRLの正規化、DCFモデル
docs/accuracy/	精度の証明 — 実測された真値はdocs/accuracy/baseline.jsonに記載されています（現在のスナップショット：近年（2010年以降）のS&P 500 FY提出書類に関する最新の数値はbaseline.jsonを参照）。FactSet PIT / FASB ASC / Penmanを引用でき、duckdb -c ".read scripts/accuracy/accuracy_check.sql"で再現できます
docs/QUERY_COOKBOOK.md	コピーして使えるDuckDBレシピ — LATERAL、ピボット、PIT、ファクタースクリーニング
docs/SDK_USE_CASES.md	最も一般的なSDKのユースケースを簡単なものから高度なものまで紹介。それぞれに、無料プランで実行したノートブックへのリンクがあります
docs/MCP_TOOLS.md	すべてのMCPツールのリファレンス — 入力、出力フィールド、プランによる制限、エラー、ページネーション（稼働中のマニフェストから生成）
docs/data_catalog.md	standard_conceptの正式名称と定義
docs/DATA_CATALOG.xlsx	同じカタログをワークブック形式で収録 — 列、型、サンプル値
docs/data_catalog.json	機械可読なカタログ（SDKのメタデータとドキュメントサイトで使用）
docs/schema.json	機械可読なテーブルおよび列のスキーマ
docs/COMPLIANCE_AND_DDQ.md	データの来歴、MNPIポリシー、PITの整合性、セキュリティ、SLAの概要
docs/SLA.md	稼働率目標、データの鮮度、サポートの応答時間、SLAクレジット

---

サポートとコミュニティ

主なサポート窓口はGitHub Issuesです。適切なテンプレートを使用してください。正しい担当先に振り分けられ、より迅速に対応できます。

内容	開く項目
不正確または疑わしいデータを報告する	データ品質レポート
機能、コンセプト、データセットをリクエストする	機能リクエスト
サービス停止またはサービス品質の低下を報告する	サービス停止
一般的な質問をする	Q&A
セキュリティ上の問題を非公開で報告する	SECURITY.mdを参照
一般的なサポートを受ける	SUPPORT.mdを参照

非公開の事項や契約に関するお問い合わせ（DPA、調達、DDQ、エンタープライズSLA）は、**[email protected]**までご連絡ください。

サンプル、ノートブックの改善、ドキュメントの修正、クエリレシピなどの貢献を歓迎します。ワークフローについてはCONTRIBUTING.md、コミュニティの行動規範についてはCODE_OF_CONDUCT.mdを参照してください。

---

商標

S&P 500®はStandard & Poor's Financial Services LLCの登録商標です。Russell®指数はFTSE Russellの商標です。Nasdaq-100®はNasdaq, Inc.の商標です。Valueinは、いずれの指数提供者とも提携、支援、推奨、ライセンス供与の関係にありません。指数の構成銘柄は、SECへの公開提出書類および公開ファンド開示情報に基づき、独自に再構築されています。

ライセンスと開示

このリポジトリのコードとドキュメントは、Apache 2.0 ライセンスの下で提供されています。帰属表示については、NOTICE をご覧ください。

無料サンプルを含むすべてのプランの Valuein データには、別途 Valuein Data Licence が適用されます。内部利用と研究、小規模な抜粋へのクレジット表示が認められますが、書面による合意なしに、再配布、転売、またはモデルのトレーニングに使用することは禁止されています。

このリポジトリは、研究および教育目的で提供されています。投資助言ではありません。 特定の取引、投資、または規制上の目的への適合性について、いかなる保証も行いません。