secedgar-mcp-server

---

概要

SEC EDGAR の提出書類、財務情報、所有権データを扱います。ティッカー、名称、または CIK で企業を検索し、1993 年までさかのぼって提出書類を検索できます。企業間の財務情報を比較し、インサイダー取引、13F 保有情報、13D／13G の大口保有者、ファンドのポートフォリオを通じて所有権を追跡できます。API キーは不要です。

ツール

ツール	説明
secedgar_company_search	企業を検索し、任意で直近の提出書類を含む事業体情報を取得します
secedgar_search_filings	1993年以降のEDGAR提出書類を検索します。全文検索は2001年以降に対応し、それ以前はアーカイブを閲覧します
secedgar_get_filing	提出書類のメタデータと文書テキストを、ページ単位またはセクション単位で取得します
secedgar_get_financials	1社と1つの概念について、過去のXBRL財務データを取得します
secedgar_get_snapshot	1回の呼び出しで財務プロフィールを取得します。対応するすべての概念の最新値を返します
secedgar_get_material_events	8-K提出書類を取得します。項目コードはデコードされ、フィルタリング可能です
secedgar_get_insider_transactions	Form 4／4-Aのインサイダー取引を、所有権XMLから解析します
secedgar_get_institutional_holdings	機関投資家の運用者1社について、四半期ごとの13F-HR保有銘柄を取得します
secedgar_find_holders	逆引き13F検索：発行体の保有を報告した運用者を検索します
secedgar_get_beneficial_owners	構造化されたSCHEDULE 13D／13G提出書類から、発行体の5％以上を保有する大口株主を取得します
secedgar_get_fund_holdings	四半期ごとのNPORT-Pレポートから、ETFおよび投資信託のポートフォリオ保有銘柄を取得します
secedgar_fetch_frames	すべての報告企業について、1つのXBRL概念と1つの期間を取得します
secedgar_compare_companies	複数の概念について企業を比較し、会計年度または暦四半期ごとに揃えます
secedgar_search_concepts	対応するXBRL概念名を見つけるか、生のタグから逆引きします
secedgar_dataframe_describe	出典情報、TTL、スキーマとともに、キャンバスのデータフレームを一覧表示します
secedgar_dataframe_query	データフレームを対象に、単一のSELECT文を実行します
secedgar_dataframe_drop	名前を指定してキャンバスのデータフレームを削除します。EDGAR_DATAFRAME_DROP_ENABLED=trueでオプトインします

リソース

リソース	説明
secedgar://concepts	財務諸表ごとにグループ化されたXBRL財務概念。わかりやすい名称をXBRLタグに対応付けます
secedgar://filing-types	一般的なSEC提出書類の種類と、2つの番号体系に対応する8-K項目コードの表です

secedgar_search_conceptsは、ツールのみをサポートするクライアントにも同じ概念カタログを提供します。

プロンプト

プロンプト	説明
secedgar_company_analysis	企業のSEC提出書類を構造的に分析します。財務動向、リスク要因、重要事象を扱います

スキル

スキル	説明
secedgar-guide	所有権に関する各質問にどのツールが答えるか、CIK、アクセッション番号、CUSIP、ファンドのシリーズIDの入手元、データが存在しないと報告する前に確認すべき対応範囲の制限を説明します

このスキルはskills/secedgar-guide/SKILL.mdに含まれています。プラグインホストはパッケージから読み込み、Skills拡張に対応するMCPクライアントは、サーバーからskill://secedgar-guide/SKILL.mdとして読み込みます。

機能リファレンス

secedgar_company_search _ツール

• queryには、ティッカー（株式、ETF、投資信託）、現在または過去の企業名、あるいはCIKを指定します。include_filings（デフォルトで有効）を指定すると、forms、filed_after、filed_beforeで絞り込んだ最大filing_limit件の提出書類が追加されます（デフォルトは10件。50件のインライン上限で提供される値は最大1,000件です）。
• SICコード、取引所、会計年度末、設立州を返します。ファンドのティッカーの場合はseries_id／class_idも返します。一致するものがない場合はno_match（data.suggestionsに類似候補を含む）、複数一致する場合はmultiple_matchesとして失敗します。
• 日付または書式によるフィルターはアーカイブまで遡れます（最大10ページ）。history_scanned_throughは、どこまで検索したかを示します。

---

secedgar_search_filings _tool

• 全文検索用のquery（フレーズ、OR、-exclusion、wildcard*、ticker:／cik:による範囲指定）、またはqueryなしでformsやエンティティによる閲覧ができます。filed_after／filed_beforeは単独でも機能します（filed_afterのみの場合は今日まで、filed_beforeのみの場合は2001-01-01から、2001年より前は1993-01-01から検索します）。limitは最大100（デフォルトは20。1,000までの値を指定した場合は100件を返します）、offsetは最大9,999（2001年以降の検索でsort: "relevance"を指定した場合のみ）
• 全文検索の対象は2001年以降です。1993年まで遡る以前の期間はアーカイブから取得します。この場合、フリーテキスト検索にはticker:／cik:による範囲指定が必要で、最大50件の文書を読み取ります（件数はscanで報告されます）
• 提出書類ごとに1行を返し、source（efts、submissions、full-index）でタグ付けします。全文検索の行にはmatched_documents（secedgar_get_filingで使用するファイル名）が含まれます。レスポンスにはtotal、form_distribution、total_is_exact、および全文検索の場合はtotal_documentsが含まれます

---

secedgar_get_filing _tool

• ハイフン区切り形式または18桁形式のaccession_number。検索を高速化するための任意のcik、添付資料を指定するdocument、XBRLアーティファクトを取得するinclude_xbrlを指定できます。ページごとのcontent_limitは1,000～200,000文字（デフォルトは50,000。1,000,000までの値を指定した場合は200,000文字を返します）
• offset／next_offsetを使ってページを進め、content_truncatedがfalseになるまで取得します。またはsection（item 1やpart iなどの見出し）を指定して移動できます。その後、sectionはoffsetより優先されるため、次のページに進む際はsectionを省略してください。切り詰められた文書の最初のページには、最大50件の見出しとオフセットを含むoutlineが付属します
• documentsは提出書類を主要文書、添付資料、補助資料に分割します。binaryエントリ（スキャン、PDF、アーカイブ）はbinary_documentエラーとなり、該当するsectionが見つからない場合はoutline付きでsection_not_foundを返します
• アーカイブから提出書類の主要文書を取得できない場合（2000～2001年に多く見られます）、代わりに提出書類全体の<accession>.txtを読み取り、その旨を通知します

---

secedgar_get_financials _tool

• company（ティッカーまたはCIK）と、わかりやすい名称またはXBRLタグのconceptを指定します。taxonomyはus-gaap（デフォルト）、ifrs-full、またはdei、period_typeはannual、quarterly、またはallです。複数の単位で報告される概念では、unitでSECの単位キー（ZAR、USD、USD/EUR）を1つ選択します。limit（1～100）でインラインの系列を絞り込みます
• 重複を除いた系列を新しい順に返します。各暦期間につき値は1つで、form、filed、accession_number、tagを含み、すべて同じunitで示されます（その他の単位はcaveatsに記載されます）。確認したタグはtags_triedに一覧表示されます。結果が空の場合は、no_concept_data、no_frame_data、no_period_data、またはno_unit_dataのエラーとなります
• conceptがわかりやすい名称でもUpperCamelCase形式のタグでもない場合は、unknown_conceptエラーとなります。標準的な組み合わせ（free_cash_flow、ebitda、working_capital）の計算式、または最も近いわかりやすい名称を最大3つ提示します

---

secedgar_get_snapshot _tool

• company、taxonomy（us-gaap（デフォルト）またはifrs-full）、period_type（annual、quarterly、またはboth（デフォルト））を指定します。companyfactsを1回読み取ることで、サポートされているすべての概念を取得します。データフレームとしてステージングされるデータはありません
• 各linesエントリには、期間概念の最新のannualおよびquarterlyの値、または貸借対照表やエンティティ情報の概念の最新のinstant値が、由来するtagとともに、その行のtaxonomyの下に報告されます。提出者が報告していない概念は、tags_triedとともにgapsに格納されます

---

secedgar_get_material_events _ツール

• company と最大20個の items コードを指定します。2004-08-23以降はドット付き（2.02）、それ以前は整数のみ（12）です。この2つの期間に重複はないため、切り替わりをまたいで組み合わせてください。filed_after / filed_before は単独でも機能し、アーカイブまで検索します。limit は1～1,000で、100件まで返されます（デフォルトは20件）。
• 各提出書類では、items が code、label、regime（current / legacy）にデコードされます。item_distribution は対象期間内の各コードの件数を示し、total_8k_scanned と total_matched の差からフィルターで除外された件数がわかります。
• 日付範囲の検索では、アーカイブのページを最大10ページ読み込みます。未読の範囲は history_scanned_through と dataset.truncated に示されます。

---

secedgar_get_insider_transactions _ツール

• company は発行体です。transaction_type は purchase（コードP）、sale（コードS）、または all（デフォルト）を指定します。limit は1～1,000で、100件まで返されます（デフォルトは20件）。Form 3とForm 5は対象外です。
• 日付範囲を指定しない場合、新しいForm 4 / 4-Aの提出書類を最大100件スキャンします。filed_after / filed_before は、どちらか一方だけでも指定でき（境界日を含む）、2003年半ば以降の任意の期間を最大100件の提出書類まで検索します。history_scanned_through には、解析した最も古い提出書類が示されます。
• 各取引には、報告者、関係、transaction_code と transaction_type、is_derivative、符号なしの shares_traded とその direction（acquire / dispose）、1株当たりの価格、取引後の保有株数が含まれます。dataset.truncated は解析対象より後の提出書類があることを示します。filings_other_issuer は、別の発行体の報告所有者として会社が提出したForm 4の件数を示します。これらのForm 4は結果に行を追加しません。価格のテキストは、固定小数点表記で数値の桁を保持し、小数点以下2桁以上を含みます。

---

secedgar_get_institutional_holdings _ツール

• company は13F提出者を指定します（CIKが最も確実です）。ポートフォリオ企業ではありません。ポートフォリオ企業の検索は secedgar_find_holders の役割です。quarter は YYYY-QN 形式で、デフォルトでは最新の提出書類が対象です。limit は1～500（デフォルトは20件。最大1,000件まで指定できますが、返されるのは500件です）で、offset / next_offset を使用できます。consolidate（デフォルトはtrue）は小計行をポジションに統合し、評価額順に並べます。
• 過去の四半期はアーカイブから検索します（最大10ページ）。13F-NTの通知のみが存在する四半期では、通知のアクセッション番号と期間を示す no_filings_found エラーが返されます。
• 保有資産、ページング、統合、データフレームは、元の13F-HRと同期間の13F-HR/A修正書類から構成される四半期を対象とします。修正書類は acceptanceDateTime の順に適用されます。RESTATEMENT は、それまでに構成されたすべての内容（先行する NEW HOLDINGS を含む）を置き換えます。NEW HOLDINGS の修正書類は行を追加します。ただし、その表が構成済みのすべての行（CUSIP、クラス、put/call、裁量、株数、株式の種類）を繰り返している場合は、修正再表示として適用されます。評価額は各アクセッションの提出日を基準に正規化されます。最後に読み取り可能な修正再表示以降の表のみを読み込みます。
• amendments（新しい提出順）は、各アクセッション、提出日、表紙の種類を示します。読み取り不能な場合は理由とともに UNAVAILABLE と表示されます。また、applied_as は restatement、new_holdings、superseded、not_applied のいずれかを示します（種類または表が読み取り不能の場合は、通知にその旨が記載されます）。詳細を確認するには secedgar_get_filing を使用してください。composed_accessions には、行の構成元となった提出書類が適用順に並びます。amendment_search_complete=false は、アーカイブの検索範囲に上限がある、またはアーカイブを利用できないため、修正書類を見落としている可能性があることを示します。
• 保有資産には、発行体、CUSIP、整数USD単位の market_value_usd、株数または元本、put_call、source_accession_numbers が含まれます（統合されたポジションには、その出所となった各提出書類が記載され、データフレームの列にも含まれます）。total_holdings_in_filing は元の13F-HRの未加工の行数、total_holdings_composed は構成後の未加工の行数、total_positions は構成後の個別ポジション数を示します。accession_number と filing_date は元の13F-HRを示します。同じ法人名が共有されている場合は、ambiguous_entity エラーが返されます。

---

secedgar_find_holders _ツール

• issuerにはティッカー、CIK、または名称を指定します。任意で9文字のcusipを指定すると、厳密に一致する検索キーとして使われます（名称のフレーズ一致では、該当範囲が広すぎたり狭すぎたりする場合があります）。quarterにはYYYY-QNを指定します。デフォルトでは、提出期限の45日を過ぎた最新の四半期が使われます。limitは1～100（デフォルトは20。最大1,000件まで対応しますが、取得件数は100件です）。最大500件の提出書類から取得します。
• 各行にはfiler_cik、accession_number、formが含まれます。また、search_mode（cusip／name）、total_filings、fetched、holders_in_quarterで結果の規模が示されます。リストに順位は付いていないため、保有ポジションを確認するにはfiler_cikをsecedgar_get_institutional_holdingsに渡してください。
• 一致する書類が取得上限を超える場合、通知にはクエリ、日付、書類オフセットを含む、続きの検索に使える正確なsecedgar_search_filings呼び出しが記載されます。results.period_endingを四半期末でフィルタリングし、サンプルのfiler_cikと検索結果のcikを照合して重複を除き、最新のfiling_dateを残してください。全ページを取得するたびに100書類ずつ進めてください。EDGARのページング上限は10,000書類です。下限として示される合計件数には、それを超える書類が含まれない場合があります。

---

secedgar_get_beneficial_owners _ツール

• issuerには保有対象の企業を指定します。form_kindはall（デフォルト）、13D、または13Gです。include_amendmentsはデフォルトでtrueです。limitは解析済みの一致書類1～20件（デフォルトは10。最大1,000件まで対応しますが、取得件数は20件です）。新しい順に最大50書類を調べ、別の発行体を記載したスケジュールは除外します。除外された書類と取得に失敗した書類はlimitに含まれません。
• 各提出書類には、各報告者の議決権、処分権、percent_of_classを含むreporting_personsが記載されます。共同提出者は同じ株式について報告するため、これらの数値を合算しないでください。13Dにはpurpose_of_transactionが含まれますが、13Gには含まれません。
• 対応範囲は、構造化XMLスケジュールの2024-12-18分から始まります。legacy_filings_before_coverageは、発行体のそれ以前のテキスト形式のSC 13D／SC 13G提出書類の件数を示します。
• total_structured_filingsはfilings_examinedとfilings_not_examinedに分かれます。調査した書類は、filings_parsed、filings_excluded_other_issuer、filings_failed.lengthに分かれます。取得に失敗したアクセッションには、document_not_found（404）またはunparseable（発行体の識別情報がない場合など）が記録され、partialが設定されます。truncatedは、結果件数の上限またはスキャン上限に達した後も未調査の索引済みスケジュールが残っていることを示し、失敗の有無とは別に判定されます。

---

secedgar_get_fund_holdings _ツール

• fundにはティッカー（VOO）、シリーズID（S000002839）、またはCIKを指定します。複数シリーズを持つ信託では、シリーズが一覧表示されたうえでseries_requiredエラーになるため、series_idを指定してください。report_dateではavailable_report_periodsから期間を選択します。limitは1～100（デフォルトは20。最大1,000件まで対応しますが、取得件数は100件）で、offset／next_offsetを使用できます。
• ポジションはpercent_of_net_assetsの大きい順に表示され、名称、CUSIP／ISIN／LEI、balanceとunits、value_usd、資産カテゴリーと発行体カテゴリーが含まれます。ファンドの純資産、総資産、総負債も表示されます。ポジションのcurrencyは表示通貨を示します。評価額はUSDのままです。パーセンテージのテキストは、固定小数点表記の数値をそのまま保持します。
• 保有状況はreport_period_date時点のもので、filing_dateの約2か月前です。publication_lag_daysにその間隔が示されます。

---

secedgar_fetch_frames _ツール

• conceptには分かりやすい名称またはタグをそのまま指定します。periodにはCY2023、CY2024Q2、またはCY2023Q4Iを指定します。taxonomyはus-gaap（デフォルト）またはdei、unitはデフォルトでUSD、sortはdesc／ascです。limitは1～100（デフォルトは25。最大1,000件まで対応しますが、取得件数は100件）で、offset／next_offsetを使用できます。
• 1回の呼び出しで検索するタグは1つです。unqueried_tagsとrelated_tagsに、個別に取得できるタグのバリエーションが一覧表示されます。value_distribution.max_to_p95_ratioはスケール外れ値を示し、period_end_rangeは会計年度の混在を示します。caveatsは会計年度第4四半期の欠落を示します。
• conceptが分かりやすい名称でもUpperCamelCaseのタグでもない場合はunknown_conceptエラーになります。形式が正しいタグに該当するフレームがない場合はno_dataになります。

---

secedgar_compare_companies _ツール

• companies は2～10社、concepts は1～8件です。taxonomy は us-gaap（デフォルト）または ifrs-full、period_type は annual（デフォルト）または quarterly、periods は1～12件（デフォルトは4件。12件の場合、最大1,000件が提供されます）です。インラインのマトリックスが大きすぎる場合は、さらに件数が絞られます
• cells は各値をカレンダー上の period に揃え、frame、period_end、ソースの tag を保持します。比較可能な年次データがない場合、呼び出しは no_comparable_data で失敗します
• failed_companies（理由は not_found、ambiguous、no_company_facts）と gaps で不足している情報を報告し、caveats で企業間の期間終了日の違いや単位の不一致を示します
• 認識されない概念はヒントとともに unknown_concepts に記載されます。すべての概念が認識されない場合に限り、呼び出しは unknown_concept で失敗します

---

secedgar_search_concepts _ツール

• search はわかりやすい名前、ラベル、タグを対象とする部分文字列検索です。そのため、NetIncomeLoss のような生のタグから、対応するわかりやすい名前を逆引きできます。group と taxonomy で絞り込めます。引数を指定しない場合は、カタログ全体が返されます
• 各概念には tags、ifrs_tags（ライブの20-F提出書類でIFRS要素が確認された場合のみ）、related_tags、unit、group が記載されます

---

secedgar_dataframe_describe _ツール

• 1つのデータフレームを指定する場合は、任意の name を指定します。省略すると、テナントのアクティブなデータフレームが新しい順に一覧表示されます
• 各エントリーには source_tool、query_params、created_at / expires_at、row_count、truncated、および secedgar_dataframe_query のSQLで一致させる必要がある column_schema が含まれます

---

secedgar_dataframe_query _ツール

• sql にDuckDBのSELECT文を1つ指定します（結合、集計、ウィンドウ関数、CTEを使用できます）。row_limit は1～10,000（デフォルトは1,000）、preview はインラインで返す行数を減らすための指定です。それぞれ10,000件単位で最大100,000件まで提供されます。register_as（df_XXXXX_XXXXX）を指定すると、結果が新しいデータフレームとして保存されます
• columns、rows、row_count、row_count_capped を返します。row_count_capped が true の場合、row_count は合計ではなく上限値です。BIGINT列は文字列としてシリアライズされます
• 書き込み、DDL、ファイル読み込み関数、複数のステートメント、システムカタログは、型付きの理由コード（non_select_statement、denied_function、multi_statement、system_catalog_access など）で拒否されます。修飾されていない current_schema は、列名として使用されていても denied_function として拒否されるため、その列を読み取る場合は <table>.current_schema と指定してください

---

secedgar_dataframe_drop _ツール

• 削除するデータフレームの name を指定します。冪等であり、一致するものがない場合は dropped: false を返します
• EDGAR_DATAFRAME_DROP_ENABLED=true でない限り無効で、無効の場合は tools/list に表示されません

---

secedgar://concepts _リソース

• 明細書ごとにグループ化された、わかりやすい名前のカタログです。text/markdown として提供され、各概念のus-gaap、IFRS、および別定義のタグが含まれます
• これらの名前は、secedgar_get_financials、secedgar_compare_companies、secedgar_fetch_frames で概念として指定できます

---

secedgar://filing-types _リソース

• 一般的なSECフォームについて、提出頻度とユースケースを text/markdown として説明します
• 2つの番号体系に対応する8-K項目コードの表と、secedgar_get_material_events の items フィルターで使用する語彙が含まれます

---

secedgar_company_analysis _{プロンプト}

• 引数：company は必須、focus_areas は任意の自由記述です
• 番号付きのワークフロー（企業検索、secedgar_get_snapshot を使った財務プロフィールの確認、secedgar_get_financials を使ったトレンド分析、提出書類の確認、重要イベントの確認、市場全体のランキング用に secedgar_fetch_frames を用いた secedgar_compare_companies による同業他社比較）と、調査結果のテンプレートを含むユーザーメッセージを1件返します。focus_areas にインサイダー、機関投資家、または大株主に関する語句が含まれる場合は、それらの所有状況を確認する手順が追加され、「ownership」が含まれる場合は3つすべてが追加されます

特長

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、切り替え可能な認証（none／jwt／oauth）、交換可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを備えています。

EDGAR 固有の機能：

• リクエストは SEC の 10 req/s の上限を超えないよう調整されます。429 が返された後は、EDGAR_RATE_LIMIT_COOLDOWN_SECONDS のカウントダウン中、呼び出しは rate_limited としてローカルで失敗し、その後にプローブが 1 回送信されます
• ティッカー（ファンドのティッカーを含む）、現在または過去の会社名、あるいは CIK の直接指定から CIK を解決し、見つからない場合は類似候補を提示します
• 履歴上のタグ変更に対応したわかりやすい XBRL コンセプト名を使用します。secedgar_get_financials、secedgar_get_snapshot、secedgar_compare_companies は同じ重複排除とタグの優先順位を共有するため、数値が一致します。また、caveats は時系列データの欠落を示します
• 提出書類は HTML からテキストに変換され、見出しを検出します。サイズの大きい提出書類にはオフセット指定のページングを利用できます
• 有効化すると、会社のティッカーと XBRL の company-facts をローカル SQLite ミラーに保存できます（EDGAR_MIRROR_ENABLED）。CIK の解決と財務データをディスクから提供します

エージェント向け出力：

• 会話内での SQL：応答に dataset フィールドを含むツールはすべて、結果全体を DuckDB データフレーム（df_<id>）として準備します。インラインリストは limit 件に制限されます。secedgar_dataframe_describe で内容を確認し、secedgar_dataframe_query でクエリを実行できます
• 判別可能な出力と明示的な欠落情報：提出書類検索の行にある source、search_mode、8-K 項目の regime、型付きの失敗理由を含む failed_companies、ゼロ埋め値の代わりに tags_tried を含む gaps
• 完全性の開示：history_scanned_through、total_is_exact、publication_lag_days、dataset.truncated により、エージェントはスキャン範囲と除外された内容を把握できます
• コンセプトごとにパラメーター名を統一：すべてのツールで company、filed_after／filed_before、forms が同じ意味を持ちます。また、よく使われる別表記（ticker、cik、start_date、end_date、form_types など）もエイリアスとして受け付けます

はじめに

インストール不要で、ホスト済みインスタンスに接続できます：

claude mcp add --transport http secedgar-mcp-server https://secedgar.caseyjhand.com/mcp

または、ローカルで実行します：

claude mcp add secedgar-mcp-server -e EDGAR_USER_AGENT="YourAppName [email protected]" -- npx -y @cyanheads/secedgar-mcp-server

ほかのクライアントでは、MCP の設定ファイルに以下を追加します：

{
  "mcpServers": {
    "secedgar-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/secedgar-mcp-server"],
      "env": { "EDGAR_USER_AGENT": "YourAppName [email protected]" }
    }
  }
}

SEC は、すべてのリクエストに "AppName [email protected]" 形式の User-Agent を求めています。アカウントやキーは不要です。Docker またはソースからビルドする場合は、サーバーの実行を参照してください。

設定

変数	説明	デフォルト
EDGAR_USER_AGENT	必須。 SEC に送信する User-Agent。"AppName [email protected]" の形式で指定します。SEC は User-Agent がない IP をブロックします。HTTP ヘッダーとして送信できない値（emダッシュや曲がった引用符、内部の改行）が指定されると、この変数名を示すエラーが発生し、サーバーの起動が停止します。	—
EDGAR_RATE_LIMIT_RPS	SEC への最大リクエスト数（1 秒あたり）。	10
EDGAR_RATE_LIMIT_COOLDOWN_SECONDS	429 の発生後、プローブリクエストを送信するまでローカルで呼び出しを拒否する秒数。	600
EDGAR_TICKER_CACHE_TTL	企業およびファンドのティッカーファイルをキャッシュする秒数。	3600
EDGAR_DATASET_TTL_SECONDS	Canvas データフレームの TTL。データフレームの操作ごとに更新されます。	86400
EDGAR_DATAFRAME_DROP_ENABLED	true に設定すると、唯一の破壊的ツールである secedgar_dataframe_drop が公開されます。	false
EDGAR_CLAMP_OVERSIZED_LIMITS	上限を超えた limit、content_limit、periods、preview、row_limit を拒否せず、上限値で処理します。上限超過を拒否するには false に設定します。	true
EDGAR_MIRROR_ENABLED	企業ティッカーと XBRL 企業ファクトのローカル SQLite ミラーを有効にします。Node/Bun のみ対応。bun run mirror:init で一度初期化します。	false
EDGAR_MIRROR_PATH	ミラーデータベースを格納するディレクトリ。	./data/edgar-mirror
EDGAR_MIRROR_REFRESH_CRON	プロセス内での更新用 cron（HTTP トランスポートのみ）。例：0 9 * * *。省略すると、bun run mirror:refresh で更新します。	—
EDGAR_MIRROR_FALLBACK_LIVE	ミラーにデータがない場合、ライブ SEC API にフォールバックします。ミラーのみの読み取りにするには false に設定します。	true
CANVAS_PROVIDER_TYPE	Canvas エンジン。none にするとデータフレームが無効になります。	duckdb
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_AUTH_MODE	認証方式：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しの引数と結果を、キー名に基づいて機密情報を伏せ、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）を上限としてログに記録します。自由形式の値に含まれる秘密情報は伏せられません。	false
OTEL_ENABLED	OpenTelemetry 計装（スパン、メトリクス、完了ログ）を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレースとメトリクス用の OTLP ベース URL。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP ログのエクスポート先（例：http://localhost:4318/v1/logs）。	—

省略可能なオーバーライドの全一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

Bun v1.4.0 以上（または Node.js v24 以上）が必要です。

• クローンとインストール：

  git clone https://github.com/cyanheads/secedgar-mcp-server.git
  cd secedgar-mcp-server && bun install
  cp .env.example .env   # set EDGAR_USER_AGENT
  

• ビルドと実行：

  bun run rebuild
  bun run start:http   # or start:stdio; HTTP listens at http://localhost:3010/mcp
  

• チェックとテストの実行：

  bun run devcheck     # Lint, format, typecheck, security
  bun run test         # Vitest test suite
  bun run lint:mcp     # Validate MCP definitions against spec
  

Docker

docker run --rm -e EDGAR_USER_AGENT="YourAppName [email protected]" -p 3010:3010 ghcr.io/cyanheads/secedgar-mcp-server:latest

イメージは、HTTP トランスポート、ポート 3010、ステートレスセッションモードをデフォルトで使用し、/var/log/secedgar-mcp-server にログを記録します。MCP クライアントから stdio 経由で実行するには、"command": "docker" と "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "EDGAR_USER_AGENT=YourAppName [email protected]", "ghcr.io/cyanheads/secedgar-mcp-server:latest"] を使用します。ローカルでビルドするには、docker build -t secedgar-mcp-server . を実行します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドします。

イメージにはミラー CLI が含まれているため、実行中のコンテナでミラーを初期化し、更新できます。

docker exec <container> bun run mirror:verify    # sync status + sample reads
docker exec <container> bun run mirror:init      # one-time bootstrap from the SEC bulk archive
docker exec <container> bun run mirror:refresh   # re-ingest after SEC rebuilds the archive

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。リソースとプロンプトを登録し、SEC クライアント、キャンバス、任意のミラーを起動します。
src/config	Zod を使用したサーバー環境変数の解析と検証を行います。
src/mcp-server/tools/definitions	ツール定義（*.tool.ts）と、登録リスト buildToolDefinitions() を格納します。
src/mcp-server/resources/definitions	XBRL の概念と提出書類の種類に関するリソース定義を格納します。
src/mcp-server/prompts/definitions	企業分析のプロンプト定義を格納します。
src/services/edgar	リクエスト間隔を調整する SEC クライアント、CIK の解決、XBRL の概念マッピングと系列の重複排除、所有権／13D／13G／NPORT-P のパーサー、8-K 項目テーブル、HTML からテキストへの変換を格納します。
src/services/edgar/mirror	企業ティッカーと XBRL の企業ファクトを格納する、オプトイン方式のローカル SQLite ミラーです。
src/services/canvas-bridge	フレームワークの DataCanvas 用アダプターです。df_<id> の命名、テーブルごとの TTL、システムカタログへの SQL アクセス拒否を行います。
scripts	ビルド、devcheck、lint のツールに加え、mirror:* コマンドを格納します。
tests	src/ の構成に対応する単体テストと統合テストを格納します。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md と AGENTS.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch を使用しないでください。
• ログには ctx.log を、ストレージには ctx.state を使用してください。
• 新しいツールは buildToolDefinitions()（src/mcp-server/tools/definitions/index.ts）に登録し、リソースとプロンプトは src/index.ts の createApp() 配列に登録してください。
• 外部の SEC EDGAR 呼び出しは、未加工のレスポンスを検証してからドメイン型に正規化し、出力スキーマを返すようにラップしてください。欠落している XBRL フィールドを捏造せず、代わりに gaps に報告してください。

コントリビューション

Issue の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。