Finance Toolkit

浏览各类网站时，我反复发现不同来源对同一财务指标的数值有明显差异。同样，各来源公布的财务报表往往也不一致，而且关于各项指标计算方法的信息十分有限。

例如，Microsoft 在 2023 年 5 月 6 日的市盈率（PE）被报告为 28.93（Stockopedia）、32.05（Morningstar）、32.66（Macrotrends）、33.09（Finance Charts）、33.66（Y Charts）、33.67（Wall Street Journal）、33.80（Yahoo Finance）和 34.4（Companies Market Cap）。这些计算都没有错，但计算方法各不相同，因此得出的结果也不同。因此，汇总多个来源的数据可能会导致错误解读，因为一个来源可能采用了与另一个来源不同的定义。而且，前提是这种定义确实可查；很多时候，底层方法都被付费订阅所屏蔽。

这就是我设计 FinanceToolkit 的原因：这是一个开源工具包，其中以最简单明了的方式列出了所有相关的财务方法（500+），让计算方法完全透明（示例）。这样，你就不必依赖那些不公开计算方法的其他服务商提供的指标。借助丰富的财务报表，它可以简化计算流程，推动采用一致且广泛通用的方法和公式。

除股票外，它还支持期权、货币、加密货币、ETF、共同基金、指数、货币市场、大宗商品、关键经济指标等，让你获取历史数据以及夏普比率、风险价值等重要的绩效和风险指标。

与之配套的是 Finance Database 🌎，这是一个包含 300.000+ 个代码的数据库，涵盖股票、ETF、基金、指数、货币、加密货币和货币市场。结合使用这两者，你可以将从 FinanceDatabase 中找到的代码输入 FinanceToolkit，开展全面的竞品分析。

---

🔌 Finance Toolkit 也可作为 MCP 服务使用

无需编写代码，即可通过 Claude、Copilot、Cursor、Windsurf 或任何兼容 MCP 的客户端查询 500+ 种方法。

• **托管版：**连接到 https://financetoolkit.jeroenbouma.com/mcp，首次使用时由 OAuth 处理其余设置。
• 本地版：uvx --from "financetoolkit[mcp]" financetoolkit-mcp-setup，自动配置客户端和 API 密钥。手动设置方法请参阅 MCP 服务文档。

也可在 Smithery、Glama、MCP Servers 等平台使用。

---

目录

1. 安装
2. 功能
   • 探索行业
   • 跟踪市场
   • 深入了解竞争对手
   • 权衡风险与回报
   • 期权市场的预期
   • 经济环境
   • 经济关系
   • 比较行业 ETF
   • 构建多元化投资组合
   • 跟踪投资组合
3. MCP 服务
4. 问答
5. 贡献
6. 提及
7. 联系

安装

安装前，不妨考虑在 GitHub 上为此项目点个星，这也有助于其他人发现该项目。

安装 Finance Toolkit 只需执行以下操作：

pip install financetoolkit -U

然后在 Python 中使用：

from financetoolkit import Toolkit

companies = Toolkit(
    tickers=['AAPL', 'MSFT'],
    api_key="FINANCIAL_MODELING_PREP_KEY",  # replace with your actual API key
)

要开始使用，你需要从 FinancialModelingPrep 获取 API 密钥。该密钥用于访问 30 多年的年度和季度财务报表数据。请注意，免费套餐每天限 250 次请求，仅提供 5 年数据，且只包含在美国交易所上市的公司。

---

---

通过此链接，你可以订阅免费套餐和高级套餐，并享受 15% 折扣。这是一个联盟链接，同时也能支持此项目。我选择 FinancialModelingPrep 作为数据来源，是因为我认为它最透明、可靠，而且价格实惠。就所提供的数据量而言，我还没有找到价格如此低廉的平台。如果你发现数据不准确，或有其他与数据相关的问题，请注意，我只是提供访问这些数据的途径，并不对数据本身的准确性负责。遇到此类问题，请使用他们的联系表单，或自行提供数据。

默认情况下，Finance Toolkit 会优先使用 Financial Modeling Prep 获取数据。如果无法从 Financial Modeling Prep 获取数据（例如，由于套餐限制或 API 密钥问题），该工具包会自动切换至 Yahoo Finance 作为备用数据源。 若要禁用此回退行为并仅使用 Financial Modeling Prep，请在初始化 Toolkit 时设置 enforce_source="FinancialModelingPrep"。此配置会确保在无法访问 Financial Modeling Prep 数据时引发错误。或者，你也可以设置 enforce_source="YahooFinance"，以仅使用 Yahoo Finance 作为数据源。

enforce_source 参数也可以在调用 get_historical_data、get_treasury_data 和四个报表函数（get_balance_sheet_statement、get_income_statement、get_cash_flow_statement 和 get_statistics_statement）时单独指定，此时它会覆盖 Toolkit 初始化时使用的设置。

功能

本节介绍 Finance Toolkit。文档中还有更多示例：每个模块页面都以“入门指南”部分开篇，内容涵盖基础知识、自定义比率的创建以及使用自己的数据集。

---

---

以下各节将完整展示对半导体行业的一次分析，每一步都会回答上一步提出的问题：该行业由哪些公司组成，它们的股票表现如何，哪些因素影响它们的利润，获得这些收益承担了多少风险，期权市场对未来有何预期，经济如何影响了这一切，选择基金是否是更好的入场方式，以及该行业如何融入多元化投资组合。Finance Toolkit 的每个模块都会在此出现一次，但每个模块的功能远不止于此：总计有 500 多种方法，全部都在文档中配有示例说明。

发现行业

分析始于一组公司。Discovery 模块无需预先提供股票代码，即可通过股票筛选器、行业表现、新闻以及公司、ETF、指数、货币、加密货币和大宗商品列表找到它们。

下面的筛选器用于查找 NASDAQ 上市、价值超过 1000 亿美元的半导体公司：

from financetoolkit import Discovery

# Initialize the standalone Discovery module
discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

# Find US semiconductor companies worth more than $100 billion
semiconductors = discovery.get_stock_screener(
    industry="Semiconductors",
    country="US",
    exchange="NASDAQ",
    market_cap_higher=100_000_000_000,
    is_etf=False,
)

# Show the five largest
semiconductors[["Name", "Market Cap", "Beta", "Price", "Dividend"]].head()

例如，筛选器返回的五家最大公司如下所示。

股票代码	名称	市值	Beta	价格	股息
NVDA	NVIDIA Corporation	5084136000000	2.216	210.96	0.28
AVGO	Broadcom Inc.	1535581254973	1.476	321.68	2.6
MU	Micron Technology, Inc.	992877621000	2.226	877.55	0.565
AMD	Advanced Micro Devices, Inc.	843646776955	2.454	516.79	0
INTC	Intel Corp.	459679713584	2.23	86.96	0

下图按市值对所有公司进行排名。

## 跟踪市场

本指南的其余部分将跟踪其中三家公司：Nvidia、AMD 和 Intel。只需一行代码，就能将它们载入 Toolkit，S&P 500 也会作为基准一并载入：

from financetoolkit import Toolkit

# Initialize the Toolkit for Nvidia, AMD and Intel from 2018 to 2025
companies = Toolkit(
    ["NVDA", "AMD", "INTC"],
    api_key="FINANCIAL_MODELING_PREP_KEY",
    start_date="2017-12-31",
    end_date="2025-12-31",
)

历史数据按日、周、月、季度或年度提供，并包含每个周期的收益率和累计收益率；损益表、资产负债表和现金流量表也按年度或季度提供。股价涨了多少是一回事，涨势是否过头则是另一回事。技术指标模块通过 50 多种指标来回答这个问题，例如相对强弱指数（RSI）。RSI 的取值范围为 0 到 100，通常高于 70 会被视为超买：

# Obtain weekly market data for all tickers and the benchmark
historical_data = companies.get_historical_data(period="weekly")

# The 14-week Relative Strength Index
relative_strength_index = companies.technicals.get_relative_strength_index(period="weekly", window=14)

# Show the highest RSI of each year
relative_strength_index.groupby(relative_strength_index.index.start_time.year).max()

例如，下表展示了每年 RSI 的周度最高值。

日期	NVDA	AMD	INTC	基准
2018	66.1087	90.9719	66.7363	66.0498
2019	73.8156	81.2446	69.8225	75.9305
2020	85.2337	82.1215	78.4827	80.2378
2021	85.1593	82.0983	71.5862	74.4751
2022	58.4343	58.9426	61.2806	59.9225
2023	87.5129	77.506	76.2332	71.4291
2024	91.0702	82.1403	67.6949	80.0566
2025	73.3514	82.5281	79.7429	71.6939

下图展示了这三家公司的累计收益率与 S&P 500 的对比，下面则是 RSI。

深入比较竞争对手

Nvidia 的股价远远跑赢另外两家，这不禁让人想知道它的业务表现是否也同样出色。Toolkit 会根据财务报表计算 80 多种比率，分为五类：效率、流动性、盈利能力、偿债能力和估值。每种比率都有对应的函数，而 collect_ 函数可以一次返回整个类别：

# Collect all Profitability Ratios for all tickers
profitability_ratios = companies.ratios.collect_profitability_ratios()

# Show the first ratios for Nvidia
profitability_ratios.loc["NVDA"].head()

例如，下表展示了 Nvidia 的部分盈利能力比率。

	2017	2018	2019	2020	2021	2022	2023	2024	2025
毛利率	0.5993	0.6121	0.6199	0.6234	0.6493	0.5693	0.7272	0.7499	0.7107
营业利润率	0.3305	0.3247	0.2607	0.2718	0.3731	0.1566	0.5412	0.6242	0.6038
净利润率	0.3137	0.3534	0.2561	0.2598	0.3623	0.1619	0.4885	0.5585	0.556
EBITDA 利润率	0.3509	0.347	0.2956	0.3376	0.4167	0.2138	0.566	0.6385	0.617
自由现金流利润率	0.2995	0.2683	0.3913	0.2815	0.3021	0.1412	0.4435	0.4663	0.4477

下图展示了其中几项比率的最新值及其历年变化。

高股本回报率可能来自利润率、周转率或债务。[模型](https://www.jeroenbouma.com/projects/financetoolkit/docs/models) 会结合这些比率来区分： [扩展杜邦分析](https://www.jeroenbouma.com/projects/financetoolkit/docs/models#get_extended_dupont_analysis) 将股本回报率拆分为五个相乘后得出该回报率的组成部分：利息负担、税负、营业利润率、资产周转率和权益乘数。

# Get the Extended DuPont Analysis for all tickers
extended_dupont_analysis = companies.models.get_extended_dupont_analysis()

# Show the results for Nvidia
extended_dupont_analysis.loc["NVDA"]

例如，下方展示了 Nvidia 的各项组成部分。

	2017	2018	2019	2020	2021	2022	2023	2024	2025
利息负担比率	0.9956	1.0242	1.0436	0.9729	0.99	0.9898	1.0257	1.0316	1.0848
税负比率	0.9534	1.0629	0.9414	0.9825	0.981	1.0447	0.88	0.8674	0.8488
营业利润率	0.3305	0.3247	0.2607	0.2718	0.3731	0.1566	0.5412	0.6242	0.6038
资产周转率	0.9215	0.9551	0.7134	0.7233	0.7376	0.6319	1.1397	1.4718	1.3564
权益乘数	1.5931	1.4592	1.4205	1.5846	1.6775	1.7525	1.6428	1.4499	1.3456
股本回报率	0.4605	0.4926	0.2595	0.2978	0.4483	0.1793	0.9146	1.1918	1.0149

下方还按每个财年展示了各项组成部分，最新值位于顶部；这些组成部分相乘后得出股本回报率。

其他模型包括加权平均资本成本、Altman Z-Score、Piotroski F-Score和内在估值。几乎每个函数也都接受 growth=True，用于计算从一个期间到下一个期间的增长；接受 trailing=4，用于计算过去十二个月的数据；还接受 standardize=True，用于计算 Z-Score。

权衡风险与回报

优秀的企业并不意味着股价走势平稳。市场数据会提供给表现和风险模块，用于计算任意时段的指标，涵盖盘中到年度周期：

# The annualized Sharpe Ratio for each year
sharpe_ratio = companies.performance.get_sharpe_ratio(period="yearly", annualize=True)

# The deepest fall within each year
maximum_drawdown = companies.risk.get_maximum_drawdown(period="yearly", within_period=True)

# Show the Sharpe Ratios
sharpe_ratio

例如，下方展示了年度夏普比率。

日期	NVDA	AMD	INTC
2018	-0.613	1.1009	0.161
2019	1.5458	1.9143	1.048
2020	1.656	1.419	-0.0445
2021	2.0003	1.2366	0.2976
2022	-0.8393	-1.0532	-1.5306
2023	2.6986	1.9195	1.8358
2024	2.0851	-0.2615	-1.5749
2025	0.8325	1.1753	1.2061

下方还按年份绘制了这两项指标：最大回撤和标普 500 指数。

这两个模块合计涵盖 70 多项指标，例如风险价值、GARCH、詹森阿尔法、资本资产定价模型和 Fama-French 因子。其中大多数还支持 rolling=<n>，用于获取随时间变化的数值。

期权市场的预期

过去展现了获得这些回报伴随多大风险；期权市场则为未来的风险定价。期权模块使用 Black-Scholes、二项式模型等方法为期权定价，计算三阶以内的希腊值，并读取实时期权链：看跌看涨比率、最大痛点、做市商伽马敞口、波动率偏斜和期限结构，以及隐含波动幅度。由于期权链反映的是今天的数据，下面的 Toolkit 运行至今天，数据则是本 README 上次更新当日的数据：

# Initialize the Toolkit up to today, as the option chains are live
companies_today = Toolkit(["NVDA", "AMD", "INTC"], api_key="FINANCIAL_MODELING_PREP_KEY")

# The volatility the options imply for the next 30 days against that of the past 30 days
companies_today.options.get_volatility_risk_premium(days=30)

隐含波动率不依赖模型，它使用 VIX 背后的方法，根据到期时间附近所有价外期权计算得出；实现波动率则是相同天数内每日收益率的波动率。例如，下表展示了每家公司这两项数据。

	隐含波动率	实现波动率	波动率风险溢价	方差风险溢价	隐含波动率与实现波动率之比
NVDA	0.4845	0.2795	0.2049	0.1566	1.7331
AMD	0.657	0.498	0.159	0.1836	1.3192
INTC	0.6991	0.5196	0.1795	0.2188	1.3456

期权通常会为风险定出比实际结果更高的价格，因为卖方希望获得承担风险的报酬。这里，期权定价所反映的未来一个月波动，远高于过去一个月的实际波动：Nvidia 的期权隐含的波动率是其股价实际波动率的 1.7 倍。下图将每家公司的隐含波动率和实现波动率并列展示。

## 经济环境

这三家公司均在美国上市，其估值取决于数年后的盈利，因此美国的通胀和利率构成了影响其股价的背景。2022 年，上方的最大回撤数据显示这三家公司的股价均下跌了一半以上；当年通胀率达到 9%，美联储则将政策利率从 0.12% 上调至 4.38%。

经济模块覆盖 60 多个国家和 50 多项指标，涵盖 GDP、失业率、货币供应量和利率等；固定收益模块则增加了债券收益率、收益率曲线、央行利率以及债券和衍生品估值。两个模块都可通过同一个 Toolkit 实例访问，也可以单独使用 from financetoolkit import Economics, FixedIncome：

# Inflation on the same month a year earlier and the Federal Reserve's policy rate
inflation_rate = companies.economics.get_inflation_rate("United States", period="monthly")
policy_rate = companies.economics.get_central_bank_policy_rate("United States", period="monthly")

# The daily U.S. Treasury par yield curve
treasury_rates = companies.fixedincome.get_treasury_rates()

# Show the curve on the last trading day of each year
treasury_rates.groupby(treasury_rates.index.year).last()

例如，下表展示了每年年末的收益率曲线。

日期	1 Month	2 Month	3 Month	6 Month	1 Year	2 Year	3 Year	5 Year	7 Year	10 Year	20 Year	30 Year
2018	0.0244	0.0245	0.0245	0.0256	0.0263	0.0248	0.0246	0.0251	0.0259	0.0269	0.0287	0.0302
2019	0.0148	0.0151	0.0155	0.016	0.0159	0.0158	0.0162	0.0169	0.0183	0.0192	0.0225	0.0239
2020	0.0008	0.0008	0.0009	0.0009	0.001	0.0013	0.0017	0.0036	0.0065	0.0093	0.0145	0.0165
2021	0.0006	0.0005	0.0006	0.0019	0.0039	0.0073	0.0097	0.0126	0.0144	0.0152	0.0194	0.019
2022	0.0412	0.0441	0.0442	0.0476	0.0473	0.0441	0.0422	0.0399	0.0396	0.0388	0.0414	0.0397
2023	0.056	0.0559	0.054	0.0526	0.0479	0.0423	0.0401	0.0384	0.0388	0.0388	0.042	0.0403
2024	0.044	0.0439	0.0437	0.0424	0.0416	0.0425	0.0427	0.0438	0.0448	0.0458	0.0486	0.0478
2025	0.0374	0.0367	0.0367	0.0359	0.0348	0.0347	0.0355	0.0373	0.0394	0.0418	0.0479	0.0484

下图绘出了每年年末的收益率曲线。2021 年，短端收益率几乎为零；一年后，各期限收益率均升至 4% 以上。当短期收益率高于长期收益率时，例如 2022 年和 2023 年年末，收益率曲线便呈倒挂状态。

## 经济关系

利率上升，股价下跌，但 10 年期美国国债收益率由两部分构成：实际收益率，即投资者要求的高于通胀的回报；以及他们对这 10 年间通胀的预期。计量经济学模块使用基于 statsmodels 和 linearmodels（pip install financetoolkit[econometrics]）构建的回归、检验和预测，区分这些驱动因素。通过 Toolkit，它可以分析其中各个股票代码的收益；也可以独立使用 Econometrics(data=...) 分析任意数据。下面是三家公司月度收益与美国 10 年期实际收益率月度变化及 10 年期通胀预期月度变化的数据：

import pandas as pd

from financetoolkit import Econometrics

# The US 10-year real yield and inflation expectations at the end of each month
real_yield = companies.economics.get_real_yield_curve("United States", period="monthly")
inflation_expectations = companies.economics.get_breakeven_inflation_expectations(
    "United States", period="monthly"
)

# The monthly change in both next to the monthly returns
monthly_returns = companies.get_historical_data(period="monthly")["Return"][["NVDA", "AMD", "INTC"]]
monthly_returns["Real Yield"] = real_yield[("United States", "10Y")].diff()
monthly_returns["Inflation Expectations"] = inflation_expectations[("United States", "10Y")].diff()

# The data are changes already
econometrics = Econometrics(data=monthly_returns, changes=None)

# Regress the return of each company on the change in the real yield and inflation expectations
regressions = pd.concat(
    {
        ticker: econometrics.get_ols(
            dependent_ticker=ticker, independent_tickers=["Real Yield", "Inflation Expectations"]
        )
        for ticker in ["NVDA", "AMD", "INTC"]
    }
)

# Show the results for Nvidia
regressions.loc["NVDA"]

例如，下面展示了 Nvidia 的系数。

	系数	标准误差	t 统计量	P 值
截距	0.049	0.0129	3.8028	0.0003
实际收益率	-22.8132	5.6358	-4.0479	0.0001
通胀预期	18.1329	9.1029	1.992	0.0493

下方还展示了每个系数及其 95% 置信区间。实际收益率上升 0.1 个百分点时，Nvidia、AMD 和 Intel 的月度收益分别低约 2.3%、3.4% 和 1.9%，因为实际收益率越高，这些公司遥远未来的收益折现幅度就越大。通胀预期的影响小得多：只有 Nvidia 的系数接近显著。

该模块还涵盖单位根检验和协整检验、格兰杰因果检验、面板数据、因果推断、ARIMA、VAR 和 VECM 预测、状态转换、时变 beta 和配对交易。

比较该行业的 ETF

与其挑选三家公司，不如持有整个行业。 ETF 模块可分析任意基金的持仓、行业和国家权重、跟踪情况、集中度、重叠度、估值和流动性。下面比较了六只半导体基金：三只专注于美国（SOXX、XSD 和 PSI），一只全球基金（SMH），以及两只仅持有单一国家资产的基金：中国（SMHC）和韩国（KCHP）：

# Initialize the Toolkit for six semiconductor funds
funds = Toolkit(
    ["SOXX", "XSD", "PSI", "SMH", "SMHC", "KCHP"],
    api_key="FINANCIAL_MODELING_PREP_KEY",
    start_date="2017-12-31",
    end_date="2025-12-31",
)

# Where each fund invests, how concentrated it is and how much the funds hold of the same
country_weightings = funds.etf.get_country_weightings()
concentration = funds.etf.get_concentration()
overlap = funds.etf.get_overlap()

# Show the overlap between every pair of funds
overlap.round(2)

例如，下方展示了每对基金之间的重叠度：两个投资组合中相同部分的占比。这里使用的是当日持仓，因为基金只会公布当前持仓。

	SOXX	XSD	PSI	SMH	SMHC	KCHP
SOXX	1	0.38	0.46	0.7	0	0
XSD	0.38	1	0.34	0.28	0	0
PSI	0.46	0.34	1	0.38	0	0
SMH	0.7	0.28	0.38	1	0	0
SMHC	0	0	0	0	1.08	0
KCHP	0	0	0	0	0	1

三只美国基金和 SMH 持有的公司大多相同，其中 SOXX 和 SMH 的投资组合有 70% 重叠。SMH 持有的美国以外资产最多，其中 9% 在台湾，6% 在荷兰。中国和韩国基金与其他基金没有任何重叠，这就是在单一行业内实现多元化的样子。下方将各基金的国家权重与重叠度并列绘出。

构建多元化投资组合

基金将风险分散到整个行业，但这个行业仍会整体波动。投资组合 模块可使用任意 Toolkit 中的代码构建投资组合：最小方差、最大夏普比率、均值—方差、风险平价、层次风险平价、最小 CVaR 和 Black-Litterman 权重、有效前沿、风险贡献、压力测试和归因。下方将半导体基金与医疗保健（XLV）、能源（XLE）、长期国债（TLT）和黄金（GLD）组合：

# Initialize the Toolkit for funds across sectors and asset classes from 2021 to 2025
assets = Toolkit(
    ["SMH", "XLV", "XLE", "TLT", "GLD"],
    api_key="FINANCIAL_MODELING_PREP_KEY",
    start_date="2021-01-01",
    end_date="2025-12-31",
)

# The efficient frontier and the maximum Sharpe ratio portfolio, with at most 40% per asset
efficient_frontier = assets.portfolio.get_efficient_frontier(points=25, maximum_weight=0.4)
maximum_sharpe = assets.portfolio.get_maximum_sharpe_weights(maximum_weight=0.4)

# The portfolio in which every asset contributes the same share of the risk
risk_parity = assets.portfolio.get_risk_parity_weights()

# Show the risk parity portfolio
risk_parity

例如，下方展示了风险平价投资组合。收益和波动率均按年化计算，风险贡献表示每项资产在投资组合波动率中所占的份额。

	权重	预期收益	波动率	夏普比率	风险贡献
SMH	0.1008	0.3067	0.3508	0.7782	0.2
XLV	0.2358	0.0901	0.1449	0.3889	0.2
XLE	0.1481	0.2463	0.2672	0.7954	0.2
TLT	0.275	-0.0748	0.1606	-0.6756	0.2
GLD	0.2403	0.1681	0.1562	0.8603	0.2
投资组合	1	0.1084	0.1085	0.6888	1

下方还绘出了有效前沿，并列展示两个投资组合和各项资产本身，以及两个投资组合的权重。

## 跟踪投资组合

纸面上的最优权重仍需实际持有。Portfolio 类会随时间跟踪投资组合，投资组合可以按权重、持有的股票份额、自行记录的交易，或 60/40 和全天候投资组合等 13 种经典投资组合之一来表示。以下示例将风险平价权重从 2021 年初开始投入，每年调整回目标权重，并跟踪至今：

from financetoolkit import Portfolio

# Invest the risk parity weights and rebalance every year
portfolio = Portfolio(
    weights=risk_parity,
    start_date="2021-01-01",
    rebalancing="yearly",
    api_key="FINANCIAL_MODELING_PREP_KEY",
)

# Get an overview of the positions against the benchmark
overview = portfolio.get_portfolio_overview()

# Show the main figures
overview[["Weight", "Return", "Benchmark Return", "Volatility", "Alpha", "Beta"]]

例如，下方展示了每个持仓的主要数据。

标识符	权重	回报	基准回报	波动率	Alpha	Beta
GLD	0.1969	0.9399	0.849	0.2845	0.0909	0.8392
SMH	0.1307	2.0669	0.5236	0.4001	1.5433	2.4046
TLT	0.2273	-0.2038	0.7457	0.096	-0.9494	0.2198
XLE	0.2034	1.5458	0.2236	0.2212	1.3222	-0.4119
XLV	0.2418	0.5502	0.7995	0.1632	-0.2493	0.256
Portfolio	1	0.9703	1.1143	0.1047	-0.144	0.5075

下方绘制了每个持仓的回报与同期基准回报的对比图。

使用 portfolio.toolkit，投资组合（即所有持仓按时间加权后的总和）会加载到 Toolkit 中，因此也可以为其计算上述所有指标。

MCP 服务

Finance Toolkit MCP 服务可向任何支持 Model Context Protocol（MCP）的 AI 助手直接提供 500 多种金融方法。只需用日常语言提问，AI 就会代表你获取实时金融数据；数据由 Finance Toolkit 透明、开源的计算方法提供支持。

请参阅下方 Claude Desktop 中 Finance Toolkit MCP 服务的使用示例：

https://github.com/user-attachments/assets/96ad5288-d83d-4497-a345-1841c48c29d5

远程服务

直接连接托管服务：https://financetoolkit.jeroenbouma.com/mcp。无需在本地安装任何内容。首次连接时，客户端会打开 OAuth 授权页面并提示输入 FMP API 密钥；输入一次后，服务会负责后续身份验证。

客户端	步骤
Claude Desktop	自定义 → 连接器 → 添加自定义连接器 → 粘贴 URL
Claude.ai	自定义 → 连接器 → 添加自定义连接器 → 粘贴 URL
Claude Code	claude mcp add --transport http finance-toolkit https://financetoolkit.jeroenbouma.com/mcp
VS Code	命令面板 → MCP: 添加服务 → HTTP → 粘贴 URL
Cursor	设置 → 功能 → MCP 服务 → 添加新服务 → http → 粘贴 URL
Windsurf	设置 → MCP 服务 → 添加服务 → 远程/HTTP → 粘贴 URL

本地安装

运行设置向导，它会定位客户端的配置文件并自动写入 MCP 配置项，包括 API 密钥：

uvx --from "financetoolkit[mcp]" financetoolkit-mcp-setup

如需手动配置，请将以下内容添加到客户端的 MCP 配置文件中（例如 claude_desktop_config.json、.cursor/mcp.json、.vscode/mcp.json）：

{
  "mcpServers": {
    "finance-toolkit": {
      "command": "uvx",
      "args": ["--from", "financetoolkit[mcp]", "financetoolkit-mcp"],
      "env": { "FINANCIAL_MODELING_PREP_API_KEY": "YOUR_API_KEY_HERE" }
    }
  }
}

或者，下载 Finance Toolkit MCPB bundle，并使用 Claude Desktop 打开。安装对话框会提示输入 FMP API 密钥。

问题与解答

本节列出了常见问题，旨在澄清某些结果和／或与其他来源存在偏差的情况。如果这里没有解答你的问题，欢迎通过下方的联系方式与我联系。

如何处理财年不同的公司？

对于任何财务报表，我都会确保将其与对应的日历期间对齐。例如，Apple 的 2023 年第四季度对应的是 2023 年 7 月至 9 月。这与日历季度的第三季度相对应，因此我会将 Apple 的数据标准化为 2023 年第三季度。这样做是为了便于比较财年不同的公司。

为什么财务报表中的数字有时会与 FinancialModelingPrep 的数据不同？

查看 Hyundai Motor Company（股票代码：005380.KS）这类公司时，你会发现财务报表以 KRW（韩元）报告。由于这个股票代码在韩国交易所上市，历史市场数据也会以 KRW 报告。不过，如果你使用在美国场外交易市场上市的股票代码 HYMTF，历史市场数据则会以 USD 报告。为了解决这种差异，系统会获取年末或季度末的汇率，并将财务报表转换为 USD。这样做是为了避免自由现金流收益率（基于市值）或市盈率（基于股价）等比率计算出错。你可以在 Toolkit 初始化时设置 convert_currency=False 来禁用此功能。建议始终使用公司所在国家／地区交易所上市的股票代码。

如何获取 TTM（过去十二个月）和增长指标？

大多数函数都提供 trailing 参数，用于定义计算滚动指标时采用的期间数。例如，如果你在 Toolkit 初始化时设置了 quarterly=True，并希望计算滚动 12 个月（TTM）市盈率，可以设置 trailing=4。增长指标同样如此，可以通过设置 growth=True 来计算。该参数会根据上一期间计算每个期间的增长。此外，还有 lag 参数，可用于定义滞后增长。你还可以组合使用滚动和增长参数来计算滚动增长。例如，为市盈率设置 trailing=4 和 growth=True，即可计算 TTM 增长。

Finance Toolkit 每次运行时都会获取相同的数据吗？

不会。来自外部来源的所有数据（财务报表、历史价格、经济指标、收益率曲线、新闻等）都会自动缓存到本地 SQLite 数据库中，并在下次运行时重复使用；这适用于 Toolkit，以及 Economics、Fixed Income、Discovery 和 Portfolio 模块。Finance Toolkit 自行计算的内容（例如比率、模型和风险指标）不会缓存：每次都会根据这些数据按需计算，因此结果会反映 Finance Toolkit 的最新版本。

缓存数据不会过时。每个数据集在可能发生变化后都会重新获取：价格和财务报表在一天后重新获取（价格仅重新获取最近一周的数据，因为更早的价格数据不会再变动）；报价在一分钟后重新获取；公司简介在一个月后重新获取；经济数据发布则根据其发布频率重新获取。来源没有数据的答复（例如某家公司的 ETF 持仓）也会缓存，但请求失败（例如触发速率限制）则不会缓存。

缓存会按股票代码和日期范围记录已有数据，因此更改参数不会丢弃其他缓存数据：

• 重复相同的请求，不会检索到任何内容。
• 扩大时间范围，只会检索到缺失的年份。
• 添加股票代码，只会检索到该股票代码的数据。

数据库位于你的用户配置目录中，与 MCP 服务使用的目录相同，因此二者共用同一个缓存。你可以选择存储位置，也可以关闭缓存：

from financetoolkit import Economics, Toolkit

# Store the cache in a specific folder
toolkit = Toolkit(["AAPL", "MSFT"], use_cached_data="datasets")

# Retrieve everything every time
toolkit = Toolkit(["AAPL", "MSFT"], use_cached_data=False)
economics = Economics(use_cached_data=False)

将 FINANCE_TOOLKIT_CACHE_ENABLED 环境变量设为 0，即可在所有位置默认关闭缓存。这适用于不应将任何内容写入磁盘的环境，例如持续集成任务。FINANCE_TOOLKIT_CACHE_DB 则可将共享数据库移至其他文件。

若要查看当前存储的内容，请使用 toolkit.get_cache_contents()。该方法会按来源和数据集分组报告条目：

source	dataset	entities	entries	oldest_write	newest_write
FinancialModelingPrep	historical	2	2	2025-01-14 09:12:03	2025-01-14 09:12:05
FinancialModelingPrep	statements	2	2	2025-01-14 09:12:01	2025-01-14 09:12:02

Finance Toolkit 不会自行清除缓存，即使其内部结构发生变化也不会。只有在你明确调用 toolkit.clear_cache() 时才会删除数据，而且可以指定范围，而不是全部清除：

# Remove only the price history of a single ticker
toolkit.clear_cache(source="FinancialModelingPrep", ticker="AAPL")

# Remove everything retrieved from the OECD
toolkit.clear_cache(source="OECD")

# Remove the entire cache, which has to be confirmed
toolkit.clear_cache(confirm=True)

source 名称与 enforce_source 参数使用的名称相同，因此，“FinancialModelingPrep”和“YahooFinance”在这两处的含义一致。

获取历史数据时自动获取的“基准”是什么？

这与 benchmark_ticker 参数有关，该参数默认设为 “SPY”（标普 500）。计算夏普比率或特雷诺比率等需要市场收益率的绩效指标时，这一点很重要。你可以在初始化 Toolkit 时将 benchmark_ticker=None，以禁用此功能。

数据收集似乎很慢，可能是什么原因？

通常，检索 100 个股票代码的历史数据应少于 15 秒。如果耗时长得多，可能是达到了 API 限制（Starter 计划每分钟有 250 次请求）、网络连接较慢，或代码未经过优化所致。Finance Toolkit 会通过共享连接，使用数量有限的工作线程池收集数据（默认 10 个，可通过 FINANCETOOLKIT_MAX_WORKERS 环境变量配置），因此建议初始化 Toolkit 时一次性传入所有要分析的股票代码，而不是逐个传入。如果耗时超过 10 分钟，可以查看这个问题，其中提供的解决方案解决了该问题。

我在公司代理服务器后工作，并遇到“certificate verify failed”错误，该如何解决？

许多公司网络会检查加密流量。代理服务器会代表你打开每个 HTTPS 连接，并提供由公司自己的根证书签名的证书，而不是网站的真实证书。由于 IT 已将该根证书安装在你的计算机上，浏览器会信任它，但 Python 不会：Python 会使用自己的公共证书颁发机构列表（certifi 包）检查证书，而该列表不包含公司的证书。因此会出现类似 SSLError: certificate verify failed: self-signed certificate in certificate chain 的错误。

如果证书无法通过验证，Finance Toolkit 会先尝试使用操作系统的证书文件（如果 Python 能找到该文件；通常在 Linux 上可以，在 Windows 上则不行）。如果这样仍然失败，接下来会如何处理取决于请求是否携带 API 密钥：

• 对于不需要 API 密钥的请求，例如发往 ECB、Eurostat 或 BIS 的请求，系统会在不验证证书的情况下重试。发生这种情况时会记录一条警告。
• 对于需要 API 密钥的请求，例如发往 FinancialModelingPrep 和 FRED 的请求，系统不会在不验证证书的情况下重试。密钥包含在网址中，因此，任何能够拦截未验证连接的人都可能读取密钥并使用你的订阅。请求会失败，并显示解释下列选项的错误。

推荐的解决方案是让 Python 信任你公司的根证书，这样每个连接都会经过验证：

1. 获取 .pem（或 .crt）格式的根证书文件。通常可以向 IT 部门索取。你也可以在浏览器中打开任意 HTTPS 网站的证书详情，导出证书链中的顶级证书（在 Windows 上选择“Base-64 encoded”）。

2. 将它与 Python 的公共证书合并。下一步会替换而不是追加到 Python 的证书列表，因此如果不包含公共证书，所有未通过代理的连接都会失败：

   # 显示 Python 公共证书的位置
   python -c "import certifi; print(certifi.where())"
   
   # macOS 和 Linux：将两者合并到一个文件中
   cat /path/printed/above/cacert.pem /path/to/company-root.pem > ~/combined-certificates.pem
   

   在 Windows 上，你可以用文本编辑器打开这两个文件，然后将公司证书粘贴到 cacert.pem 副本的末尾。

3. 使用 Finance Toolkit 前，将 REQUESTS_CA_BUNDLE 指向合并后的文件：

   # macOS 和 Linux，例如在 ~/.bashrc 或 ~/.zshrc 中
   export REQUESTS_CA_BUNDLE=~/combined-certificates.pem
   
   # Windows（PowerShell）：对之后打开的每个窗口生效
   setx REQUESTS_CA_BUNDLE "C:\Users\you\combined-certificates.pem"
   

   setx 不会更改运行它的窗口，因此之后请打开一个新终端（或重启编辑器）。

   或者，在 Python 中的第一次请求之前设置它：

   import os
   
   os.environ["REQUESTS_CA_BUNDLE"] = "/path/to/combined-certificates.pem"
   
   from financetoolkit import Toolkit
   

   使用 MCP 服务时，请将此变量添加到 AI 助手配置中该服务的 env 部分。

或者，如果你公司的根证书已安装在操作系统中（受管理的 Windows 和 macOS 计算机通常如此），truststore 包可以让 Python 直接使用操作系统的证书。使用 pip install truststore 安装，然后在脚本开头运行 import truststore; truststore.inject_into_ssl()。

如果这些方法都不可行，你可以自行承担风险，将 FINANCETOOLKIT_ALLOW_UNVERIFIED_SSL=1 设为环境变量，以允许发送带有 API 密钥且不验证证书的请求，设置方式与上文相同。仅在你信任的网络上这样做：此时连接会加密到响应连接的一方，而对方可能并非你以为正在通信的网站，并且他们可以读取你的 API 密钥。

你是 FinancialModelingPrep 的成员吗？

*不是。*我只是选择他们作为主要数据提供商，因为他们提供了慷慨的免费方案，与其他提供商相比价格也公道。因此，任何与数据相关的问题都请通过他们的联系表单提交。至于各种比率、绩效指标、风险指标、技术指标或经济指标，欢迎联系我，因为这些都是我自己的工作。

贡献

首先，感谢你抽出时间参与贡献（或至少阅读贡献指南）！🚀

---

---

Finance Toolkit 的目标是让各种金融计算尽可能透明、高效。我希望让所有人都能尽可能轻松地使用这些计算；看到许多网站也提供相同的功能（但需要付费），这让我有了充分的理由着手开发。

提及

Finance Toolkit 曾在各种博客文章、研究论文、新闻通讯和社交媒体上被提及。以下是我所了解到的一些提及。如果你还知道其他提及，欢迎联系我，我会将其添加到此列表中。

博客文章

• 使用 Finance Toolkit Python 库深入分析五大科技公司的年末财务表现与风险指标
• 探索科技巨头量化金融的最佳集成平台：1. Finance Toolkit
• 使用 Finance Database 进行投资分析
• 拨开财务迷雾：介绍由 FMP 提供支持的开源 Finance Toolkit

研究

• AI，帮我思考，但为我自己思考：通过提供不同类型的认知支持，帮助人们进行复杂决策
• 使用多 Agent 系统和 Agentic RAG 进行基本面分析

新闻通讯和社交媒体

• LinkedIn #1 和 Linkedin #2
• Facebook
• Quant Seeker
• Python Hub
• Python Weekly
• Quant Science

联系方式

如果您对 Finance Toolkit 有任何疑问，或想与我分享您一直在做的事情，欢迎通过以下方式联系我：

• 网站：https://jeroenbouma.com/
• LinkedIn： https://www.linkedin.com/in/boumajeroen/
• 电子邮件： [email protected]

如果您想支持我的工作，可以为这个软件包贡献代码，或赞助我。