mcpField
F
financial-data-collector

financial-data-collector

github.com/daymade数据与数据库1.5k888 次安装今天更新
代码仓库

关于 financial-data-collector

用于收集并验证美国上市公司的财务数据，并生成供其他财务技能使用的标准 JSON 文件。它强调标注数据来源，并明确处理缺失值及会计口径。

主要功能

  1. 01收集市场及历史财务数据
  2. 02验证完整性与数据一致性
  3. 03缺失值不以默认值填补
  4. 04注明 CapEx 与 FCF 口径
  5. 05生成符合模式的 JSON 文件

适用场景

  1. 01为公司财务分析准备数据
  2. 02在下游使用前检查收集的数据
  3. 03为 DCF 相关技能提供输入

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/daymade/claude-code-skills --skill financial-data-collector

安装后在 Claude Code 中输入/financial-data-collector确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.gitignore
references/
output-schema.md
yfinance-pitfalls.md
scripts/
collect_data.py
validate_data.py

详细介绍

金融数据收集器

使用免费的数据源，收集并验证美国上市公司的真实金融数据。 输出标准化 JSON 文件，供其他金融技能使用。

关键限制

不得使用回退值。 如果无法获取某个字段，请将其设为 null，并设置 _source: "missing"。 切勿使用默认值替代（例如 beta or 1.0）。下游技能会决定如何处理缺失数据。

必须注明数据来源。 每个数据部分都必须包含 _source 字段。

资本支出（CapEx）的符号约定： yfinance 返回的 CapEx 为负值（现金流出）。保留原始符号。在输出元数据中说明该约定。不要翻转符号。

yfinance FCF ≠ 投资银行 FCF。 yfinance FCF = 经营现金流 + CapEx（不扣除 SBC）。在输出元数据中标明这一点，以免下游 DCF 技能高估 FCF。

工作流

步骤 1：收集数据

运行收集脚本：

python scripts/collect_data.py TICKER [--years 5] [--output path/to/output.json]

脚本按以下优先级收集数据：

  1. yfinance — 市场数据、历史财务数据、Beta、分析师预估
  2. yfinance ^TNX — 作为无风险利率代理值的 10 年期美国国债收益率
  3. 用户补充 — 对于 yfinance 返回 NaN 的年份（告知用户，不要猜测）
步骤 2：验证数据
python scripts/validate_data.py path/to/output.json

检查内容：字段完整性、字段间一致性（市值 = 价格 × 股数）、数值范围合理性（WACC 为 5-20%，Beta 为 0.3-3.0）、符号约定。

步骤 3：交付 JSON

单个文件：{TICKER}_financial_data.json。架构见 references/output-schema.md。

不要创建：README、CSV、摘要报告或任何辅助文件。

输出架构（摘要）

{
  "ticker": "META",
  "company_name": "Meta Platforms, Inc.",
  "data_date": "2026-03-02",
  "currency": "USD",
  "unit": "millions_usd",
  "data_sources": { "market_data": "...", "2022_to_2024": "..." },
  "market_data": { "current_price": 648.18, "shares_outstanding_millions": 2187, "market_cap_millions": 1639607, "beta_5y_monthly": 1.284 },
  "income_statement": { "2024": { "revenue": 164501, "ebit": 69380, "tax_expense": ..., "net_income": ..., "_source": "yfinance" } },
  "cash_flow": { "2024": { "operating_cash_flow": ..., "capex": -37256, "depreciation_amortization": 15498, "free_cash_flow": ..., "change_in_nwc": ..., "_source": "yfinance" } },
  "balance_sheet": { "2024": { "total_debt": 30768, "cash_and_equivalents": 77815, "net_debt": -47047, "current_assets": ..., "current_liabilities": ..., "_source": "yfinance" } },
  "wacc_inputs": { "risk_free_rate": 0.0396, "beta": 1.284, "credit_rating": null, "_source": "yfinance + ^TNX" },
  "analyst_estimates": { "revenue_next_fy": 251113, "revenue_fy_after": 295558, "eps_next_fy": 29.59, "_source": "yfinance" },
  "metadata": { "_capex_convention": "negative = cash outflow", "_fcf_note": "yfinance FCF = OperatingCF + CapEx. Does NOT deduct SBC." }
}

包含所有字段定义的完整架构：references/output-schema.md

<correct_patterns>

正确处理缺失年份
if pd.isna(revenue):
    result[year] = {"revenue": None, "_source": "yfinance returned NaN — supplement from 10-K"}
# Report missing years to the user. Do NOT skip or fill with estimates.
保留 CapEx 符号
capex = cash_flow.loc["Capital Expenditure", year_col]  # -37256.0
result["capex"] = float(capex)  # Preserve negative
日期时间列索引
year_col = [c for c in financials.columns if c.year == target_year][0]
revenue = financials.loc["Total Revenue", year_col]
字段名称保护
if "Total Revenue" in financials.index:
    revenue = financials.loc["Total Revenue", year_col]
elif "Revenue" in financials.index:
    revenue = financials.loc["Revenue", year_col]
else:
    revenue = None

</correct_patterns>

<common_mistakes>

错误 1：为缺失数据使用默认值
# ❌ WRONG
beta = info.get("beta", 1.0)
growth = data.get("growth") or 0.02

# ✅ RIGHT
beta = info.get("beta")  # May be None — that's OK
错误 2：假定所有年份都有数据
# ❌ WRONG — 2020-2021 may be NaN
revenue = float(financials.loc["Total Revenue", year_col])

# ✅ RIGHT
value = financials.loc["Total Revenue", year_col]
revenue = float(value) if pd.notna(value) else None
错误 3：在 DCF 模型中直接使用 yfinance FCF

yfinance FCF 不会扣除 SBC。对于 META 这样的超大市值公司，SBC 每年可能达到 200-300 亿美元，使 yfinance FCF 比投资银行 FCF 高出约 30%。务必在输出中标明这一点。

错误 4：翻转 CapEx 符号
# ❌ WRONG — double-negation risk downstream
capex = abs(cash_flow.loc["Capital Expenditure", year_col])

# ✅ RIGHT — preserve original, document convention
capex = float(cash_flow.loc["Capital Expenditure", year_col])  # -37256.0

</common_mistakes>

yfinance 的已知问题

字段映射和解决方法详见 references/yfinance-pitfalls.md。

评论

支持 Markdown