While browsing a variety of websites, I repeatedly observed significant fluctuations in the same financial metric among different sources. Similarly, the reported financial statements often didn't line up, and there was limited information on the methodology used to calculate each metric.
For example, Microsoft's Price-to-Earnings (PE) ratio on the 6th of May, 2023 is reported to be 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) and 34.4 (Companies Market Cap). All of these calculations are correct, however the method of calculation varies leading to different results. Therefore, collecting data from multiple sources can lead to wrong interpretation of the results given that one source could apply a different definition than another. And that is, if that definition is even available as often the underlying methods are hidden behind a paid subscription.
This is why I designed the FinanceToolkit, this is an open-source toolkit in which all relevant financial methods (500+) are written down in the most simplistic way allowing for complete transparency of the method of calculation (proof). This enables you to avoid dependence on metrics from other providers that do not provide their methods. With a large selection of financial statements in hand, it facilitates streamlined calculations, promoting the adoption of a consistent and universally understood methods and formulas.
Beyond Equities, it supports Options, Currencies, Cryptocurrencies, ETFs, Mutual Funds, Indices, Money Markets, Commodities, Key Economic Indicators and more, allowing you to obtain historical data as well as important performance and risk measurements such as the Sharpe Ratio and Value at Risk.
Complementing this is the Finance Database 🌎, a database featuring 300.000+ symbols containing Equities, ETFs, Funds, Indices, Currencies, Cryptocurrencies and Money Markets. By utilising both, it is possible to do a fully-fledged competitive analysis with the tickers found from the FinanceDatabase inputted into the FinanceToolkit.
🔌 The Finance Toolkit is also available as an MCP Server
Query 500+ methods from Claude, Copilot, Cursor, Windsurf or any MCP-compatible client without writing code.
- Hosted: connect to
https://financetoolkit.jeroenbouma.com/mcp — OAuth handles the rest on first use.
- Local:
uvx --from "financetoolkit[mcp]" financetoolkit-mcp-setup — sets up your client config and API key automatically. See MCP Server Documentation for manual setup.
Also on Smithery, Glama, MCP Servers and more.
Table of Contents
- Installation
- Functionality
- MCP Server
- Questions & Answers
- Contributing
- Mentions
- Contact
Functionality
This section is an introduction to the Finance Toolkit. Find with the link below fully-fledged code documentation as well as Getting Started guides with many examples ranging from basic examples to creating custom ratios to working with your own datasets.
Find a variety of How-To Guides including Code Documentation for the FinanceToolkit here.
A basic example of how to use the Finance Toolkit is shown below. Every code snippet in the sections that follow builds on this same companies instance.
from financetoolkit import Toolkit
# Initialize the Toolkit for Apple and Microsoft
companies = Toolkit(["AAPL", "MSFT"], api_key="FINANCIAL_MODELING_PREP_KEY", start_date="2017-12-31")
Each ratio, indicator and metric has a corresponding function that can be called directly, for example ratios.get_return_on_equity or technicals.get_relative_strength_index. Every module also has one or more collect_ functions that return a whole category at once, e.g. ratios.collect_profitability_ratios, useful when you want everything in one call instead of assembling it metric by metric.
Three capabilities cut across nearly the whole toolkit:
rolling and trailing windows. Many metrics return one value per reporting period by default. Pass rolling=<n> to compute the metric over a sliding window instead, or trailing=<n> for a trailing sum/average (e.g. a trailing 4-quarter sum to annualize a quarterly flow) — turning a snapshot into a proper time series.growth and lag. Pass growth=True on almost any get_ or collect_ function to return the period-over-period growth instead of the raw value. lag (an int or list of ints, default 1) controls how many periods back that growth is measured against, e.g. lag=4 for year-over-year growth on quarterly data. Combine with trailing (e.g. trailing=4, growth=True) to get TTM growth.standardize (Z-Score). Most get_* methods across Economics, Ratios, Technicals, Risk, Performance, Models, Options and Fixed Income accept standardize=True, converting raw values into standard deviations from their own historical mean/std. Useful for ranking, scoring, or spotting an unusual reading across metrics that otherwise live on incompatible scales.
Every module below also has a Getting Started guide and full code documentation (formulas, parameters, worked examples) linked in its own section, see the documentation hub for the complete index.
Discovering Instruments & News
Before analyzing a ticker you often need to find it. The Discovery module is standalone and covers among other things lists of companies, cryptocurrencies, forex, commodities, ETFs and indices.
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,
)
The screener returns twelve companies, of which the five largest are shown below:
| Symbol | Name | Market Cap | Beta | Price | Dividend |
|---|
| NVDA | NVIDIA Corporation | 5677886820000 | 2.217 | 234.42 | 0.28 |
| AVGO | Broadcom Inc. | 1688566002696 | 1.457 | 354.92 | 2.60 |
| MU | Micron Technology, Inc. | 1212744628950 | 2.222 | 1073.81 | 0.53 |
| AMD | Advanced Micro Devices, Inc. | 1028957518000 | 2.476 | 631.03 | 0.00 |
| INTC | Intel Corp. | 604977329655 | 2.231 | 119.94 | 0.00 |
And below all twelve are ranked by market cap.
Furthermore, you can find in this module stock screeners, sector/industry performance and news feeds and more. Find the Getting Started guide here and the full instrument discovery documentation here.
Obtaining Historical Data
Obtain historical data on a daily, weekly, monthly or yearly basis. This includes OHLC, volumes, dividends, returns and cumulative returns for each corresponding period.
# Obtain historical market data for all tickers
historical_data = companies.get_historical_data()
# Select the results for Apple
historical_data.xs('AAPL', axis=1, level=1)
For example, a portion of the historical data for Apple is shown below.
| date | Open | High | Low | Close | Adj Close | Volume | Dividends | Return | Cumulative Return |
|---|
| 2018-01-02 | 42.54 | 43.075 | 42.315 | 43.065 | 40.78 | 1.02224e+08 | 0 | 0 | 1 |
| 2018-01-03 | 43.1325 | 43.6375 | 42.99 | 43.0575 | 40.77 | 1.17982e+08 | 0 | -0.0002 | 0.9998 |
| 2018-01-04 | 43.135 | 43.3675 | 43.02 | 43.2575 | 40.96 | 8.97384e+07 | 0 | 0.0047 | 1.0044 |
| 2018-01-05 | 43.36 | 43.8425 | 43.2625 | 43.75 | 41.43 | 9.46401e+07 | 0 | 0.0115 | 1.0159 |
| 2018-01-08 | 43.5875 | 43.9025 | 43.4825 | 43.5875 | 41.27 | 8.22711e+07 | 0 | -0.0039 | 1.012 |
And below the cumulative returns are plotted which include the S&P 500 as benchmark:
Metrics such as Volatility, Excess Return and Excess Volatility are calculated as dedicated Risk and Performance methods rather than columns on this table to create more efficient and flexible functionalities. Find the Getting Started guide here and the full historical data documentation here.
Obtaining Financial Statements
Obtain an Income Statement on an annual or quarterly basis. This can also be a balance statement or cash flow statement.
# Obtain the Income Statement for all tickers
income_statement = companies.get_income_statement()
# Select the results for Apple
income_statement.loc['AAPL']
For example, the first 5 rows of the Income Statement for Apple are shown below.
| 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 |
|---|
| Revenue | 2.29234e+11 | 2.65595e+11 | 2.60174e+11 | 2.74515e+11 | 3.65817e+11 | 3.94328e+11 | 3.83285e+11 |
| Cost of Goods Sold | 1.41048e+11 | 1.63756e+11 | 1.61782e+11 | 1.69559e+11 | 2.12981e+11 | 2.23546e+11 | 2.14137e+11 |
| Gross Profit | 8.8186e+10 | 1.01839e+11 | 9.8392e+10 | 1.04956e+11 | 1.52836e+11 | 1.70782e+11 | 1.69148e+11 |
| Gross Profit Ratio | 0.3847 | 0.3834 | 0.3782 | 0.3823 | 0.4178 | 0.4331 | 0.4413 |
| Research and Development Expenses | 1.1581e+10 | 1.4236e+10 | 1.6217e+10 | 1.8752e+10 | 2.1914e+10 | 2.6251e+10 | 2.9915e+10 |
And below the Earnings Before Interest, Taxes, Depreciation and Amortization (EBITDA) are plotted for Apple and Alphabet since 2017. Their fiscal years line up closely, so both show the same latest reported year. Find the Getting Started guide here and the full financial statement documentation here.
Obtaining Financial Ratios
Get Profitability Ratios based on the inputted balance sheet, income and cash flow statements. This can be any of the 80+ ratios within the ratios module.
# Collect all Profitability Ratios for all tickers
profitability_ratios = companies.ratios.collect_profitability_ratios()
# Select the results for Microsoft
profitability_ratios.loc['MSFT']
For example, see some of the profitability ratios of Microsoft below.
| 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 |
|---|
| Gross Margin | 0.6191 | 0.6525 | 0.659 | 0.6778 | 0.6893 | 0.684 | 0.6892 |
| Operating Margin | 0.2482 | 0.3177 | 0.3414 | 0.3703 | 0.4159 | 0.4206 | 0.4177 |
| Net Profit Margin | 0.2357 | 0.1502 | 0.3118 | 0.3096 | 0.3645 | 0.3669 | 0.3415 |
| Interest Coverage Ratio | 13.9982 | 16.5821 | 20.3429 | 25.3782 | 34.7835 | 47.4275 | 52.0244 |
| Income Before Tax Profit Margin | 0.2574 | 0.3305 | 0.3472 | 0.3708 | 0.423 | 0.4222 | 0.4214 |
And below a few of the profitability ratios of Microsoft, each with its latest value, the change over the period and its trend.
The 80+ ratios are divided into five categories: Efficiency (asset/inventory/receivables turnover, cash conversion cycle, R&D/SG&A/SBC-to-revenue), Liquidity (current, quick and cash ratios, working capital), Profitability (margins, ROE/ROA/ROIC, cash vs. effective tax rate), Solvency (debt-to-equity, debt-to-capital, interest and dividend coverage) and Valuation (P/E, PEG, Forward P/E, EV multiples, buyback and shareholder yield). It's also possible to define fully custom ratios calculated automatically from the balance sheet, income and cash flow statements. Find the Getting Started guide here and the full ratio-by-ratio documentation here.
Obtaining Financial Models
Get an Extended DuPont Analysis based on the inputted balance sheet, income and cash flow statements.
# Get the Extended DuPont Analysis for all tickers
extended_dupont_analysis = companies.models.get_extended_dupont_analysis()
# Select the results for Apple
extended_dupont_analysis.loc['AAPL']
For example, this shows the Extended DuPont Analysis for Apple:
| 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 |
|---|
| Interest Burden Ratio | 0.9572 | 0.9725 | 0.9725 | 0.988 | 0.9976 | 1.0028 | 1.005 |
| Tax Burden Ratio | 0.7882 | 0.8397 | 0.8643 | 0.8661 | 0.869 | 0.8356 | 0.8486 |
| Operating Profit Margin | 0.2796 | 0.2745 | 0.2527 | 0.2444 | 0.2985 | 0.302 | 0.2967 |
| Asset Turnover | nan | 0.7168 | 0.7389 | 0.8288 | 1.0841 | 1.1206 | 1.0868 |
| Equity Multiplier | nan | 3.0724 | 3.5633 | 4.2509 | 5.255 | 6.1862 | 6.252 |
| Return on Equity | nan | 0.4936 | 0.5592 | 0.7369 | 1.4744 | 1.7546 | 1.7195 |
The five components of the Extended DuPont Analysis multiply into the Return on Equity (ROE): interest burden × tax burden × operating margin × asset turnover × equity multiplier. Below they are shown for each year, ending in the resulting ROE.
The models module covers 10+ models in total, for example DuPont Analysis, WACC, Economic Value Added (EVA), Altman Z-Score, Beneish M-Score and the Graham Number. Find the Getting Started guide here and the full model-by-model documentation here.
Obtaining Options and Greeks
Get the Black Scholes Model for both call and put options including the relevant Greeks, in this case Delta, Gamma, Theta and Vega. This can be any of the First, Second or Third Order Greeks.
# Get Delta for all tickers across strikes and expirations
delta = companies.options.get_delta(expiration_time_range=180)
# Select the results for Apple
delta.loc['AAPL']
For example, see the delta of the Call options for Apple for multiple expiration times and strike prices below (Stock Price: 185.92, Volatility: 31.59%, Dividend Yield: 0.49% and Risk Free Rate: 3.95%):
| 1 Month | 2 Months | 3 Months | 4 Months | 5 Months | 6 Months |
|---|
| 175 | 0.7686 | 0.7178 | 0.6967 | 0.6857 | 0.6794 | 0.6759 |
| 180 | 0.6659 | 0.64 | 0.6318 | 0.629 | 0.6285 | 0.6291 |
| 185 | 0.5522 | 0.5583 | 0.5648 | 0.571 | 0.5767 | 0.5816 |
| 190 | 0.4371 | 0.4762 | 0.4977 | 0.513 | 0.5249 | 0.5342 |
| 195 | 0.3298 | 0.3971 | 0.4324 | 0.4562 | 0.474 | 0.4875 |
Which can also be plotted together with Gamma, Theta and Vega as follows:
The options module is divided into four categories: Option Pricing (Black-Scholes, Binomial Model, Implied Volatility), First-Order Greeks (Delta, Vega, Theta, Rho), Second-Order Greeks (Gamma, Vanna, Charm, Vomma) and Third-Order Greeks (Speed, Zomma, Color, Ultima). Find the Getting Started guide here and the full option pricing and Greeks documentation here.
Obtaining Performance Metrics
Get the correlations with the factors as defined by Fama-and-French. These include market, size, value, operating profitability and investment. The beauty of all functionality here is that it can be based on any period as the function accepts the period intraday, weekly, monthly, quarterly and yearly.
# Get the Fama-French factor correlations for all tickers, quarterly
factor_asset_correlations = companies.performance.get_factor_asset_correlations(period="quarterly")
# Select the results for Apple
factor_asset_correlations['AAPL']
For example, this shows the quarterly correlations for Apple:
| Mkt-RF | SMB | HML | RMW | CMA |
|---|
| 2022Q2 | 0.9177 | -0.1248 | -0.5077 | -0.3202 | -0.2624 |
| 2022Q3 | 0.8092 | 0.1528 | -0.5046 | -0.1997 | -0.5231 |
| 2022Q4 | 0.8998 | 0.2309 | -0.5968 | -0.1868 | -0.5946 |
| 2023Q1 | 0.7737 | 0.1606 | -0.3775 | -0.228 | -0.5707 |
| 2023Q2 | 0.7416 | -0.1166 | -0.2722 | 0.0093 | -0.4745 |
And below the correlations with each factor are plotted over time for both Apple and Microsoft.
Beyond Beta, CAPM and the Fama-French factors, the performance module covers around 20+ metrics in total, for example Sharpe Ratio, Sortino Ratio, Calmar Ratio, Omega Ratio and the Correlation Matrix. Most of these also support rolling=<n> for a value that evolves through time instead of one number per period. Find the Getting Started guide here and the full performance metric documentation here.
Obtaining Risk Metrics
Get the Value at Risk for each week. Here, the days within each week are considered for the Value at Risk. This makes it so that you can understand within each period what is the expected Value at Risk (VaR) which can again be any period but also based on distributions such as Historical, Gaussian, Student-t, Cornish-Fisher, or a Peak-over-Threshold Extreme Value Theory (distribution="evt") fit for the tail.
# Get the weekly Value at Risk for all tickers
companies.risk.get_value_at_risk(period="weekly", within_period=True)
| AAPL | MSFT | Benchmark |
|---|
| 2023-09-25/2023-10-01 | -0.0205 | -0.0133 | -0.0122 |
| 2023-10-02/2023-10-08 | -0.0048 | -0.0206 | -0.0108 |
| 2023-10-09/2023-10-15 | -0.0089 | -0.0092 | -0.0059 |
| 2023-10-16/2023-10-22 | -0.0135 | -0.0124 | -0.0131 |
| 2023-10-23/2023-10-29 | -0.0224 | -0.0293 | -0.0139 |
And below the Value at Risk (VaR) for Apple, Microsoft and the benchmark (S&P 500) are plotted also demonstrating the impact of COVID-19.
Beyond VaR/CVaR/Entropic VaR, the risk module covers around 20+ metrics in total, for example Conditional Drawdown at Risk, Maximum Drawdown Duration, EWMA Volatility and the Hurst Exponent. Most of these support rolling=<n> for a value that evolves through time instead of one number per period. Find the Getting Started guide here and the full risk metric documentation here.
Obtaining Technical Indicators
Get the Ichimoku Cloud parameters based on the historical market data. This can be any of the 40+ technical indicators within the technicals module.
# Get the Ichimoku Cloud for all tickers
ichimoku_cloud = companies.technicals.get_ichimoku_cloud()
# Select the results for Apple
ichimoku_cloud.xs('AAPL', axis=1, level=1)
For example, see some of the parameters for Apple below:
| Date | Base Line | Conversion Line | Leading Span A | Leading Span B |
|---|
| 2023-10-30 | 174.005 | 171.755 | 176.245 | 178.8 |
| 2023-10-31 | 174.005 | 171.755 | 176.37 | 178.8 |
| 2023-11-01 | 174.005 | 170.545 | 176.775 | 178.8 |
| 2023-11-02 | 174.005 | 171.725 | 176.235 | 178.8 |
| 2023-11-03 | 174.005 | 171.725 | 175.558 | 178.8 |
And below the Ichimoku Cloud of the last twelve months is plotted for Apple and Microsoft, together with the closing price.
The 40+ indicators are divided into four categories: Breadth (McClellan Oscillator, Advancers/Decliners, OBV, ADL, Chaikin Oscillator, TRIN, New Highs - New Lows), Momentum (RSI, MACD, Stochastic, Williams %R, Aroon, CCI, ADX and more), Overlap (SMA, EMA, DEMA, TRIX, WMA, Hull MA, VWAP, Parabolic SAR, Pivot Points, Support/Resistance) and Volatility (ATR, Keltner Channels, Bollinger Bands, Donchian Channels, Volatility Cone). Find the Getting Started guide here and the full technical indicator documentation here.
Obtaining Fixed Income Metrics
Get access to the ICE BofA Corporate Bond benchmark indices and a variety of other bond and derivative related valuations within the fixedincome module.
# Get the ICE BofA Effective Yield for each Credit Rating
companies.fixedincome.get_ice_bofa_effective_yield(maturity=False)
For example, see the Effective Yield for the ICE BofA Corporate Bond Index below for each Credit Rating:
| Date | AAA | AA | A | BBB | BB | B | CCC |
|---|
| 2024-04-19 | 0.0518 | 0.0532 | 0.0561 | 0.0594 | 0.0678 | 0.0804 | 0.1385 |
| 2024-04-22 | 0.0517 | 0.0532 | 0.056 | 0.0593 | 0.0671 | 0.0793 | 0.1377 |
| 2024-04-23 | 0.0514 | 0.0528 | 0.0556 | 0.0589 | 0.066 | 0.0777 | 0.1364 |
| 2024-04-24 | 0.0518 | 0.0531 | 0.0559 | 0.0592 | 0.0664 | 0.0778 | 0.1361 |
| 2024-04-25 | 0.0524 | 0.0537 | 0.0564 | 0.0598 | 0.0673 | 0.079 | 0.1368 |
And below the effective yield for each credit rating is plotted over time.
Beyond ICE BofA benchmarks, the fixedincome module covers Bond Valuations (Present Value, Macaulay/Modified Duration, Convexity, Yield to Maturity), Derivative Valuations (Black and Bachelier models for Swaptions), Government Bonds (3-month and 10-year yields) and Central Bank rates (Euribor, ECB and Federal Reserve rates incl. SOFR). It can be called via companies.fixedincome or standalone through from financetoolkit import FixedIncome. Find the Getting Started guide here and the full fixed income documentation here.
Understanding Key Economic Indicators
Get insights for 60+ countries into key economic indicators such as the Consumer Price Index (CPI), Gross Domestic Product (GDP), Unemployment Rates and 3-month and 10-year Government Interest Rates. This is done through the economics module and can be used as a standalone module as well by using from financetoolkit import Economics.
# Get the Unemployment Rate for a selection of countries
companies.economics.get_unemployment_rate()
For example see a selection of the countries below:
| Colombia | United States | Sweden | Japan | Germany |
|---|
| 2017 | 0.093 | 0.0435 | 0.0686 | 0.0281 | 0.0357 |
| 2018 | 0.0953 | 0.039 | 0.0648 | 0.0244 | 0.0321 |
| 2019 | 0.1037 | 0.0367 | 0.0691 | 0.0235 | 0.0298 |
| 2020 | 0.1586 | 0.0809 | 0.0848 | 0.0278 | 0.0362 |
| 2021 | 0.1381 | 0.0537 | 0.0889 | 0.0282 | 0.0358 |
| 2022 | 0.1122 | 0.0365 | 0.0748 | 0.026 | 0.0307 |
And below these Unemployment Rates are plotted over time:
The 40+ indicators are divided into five categories: Government (GDP, government debt/revenue/expenditure/deficit, trust in government), Economy (CPI, inflation, consumer/business confidence, house/rent/share prices), Finance (money supply, central bank policy rate, short/long-term interest rates), Environment (renewable energy, carbon footprint) and Jobs & Society (unemployment, labour productivity, income inequality, population, poverty rate). Find the Getting Started guide here and the full economic indicator documentation here.
Explore your own Portfolio
Through a custom XLSX, XLS or CSV file you are able to load in your own portfolio directly into the Finance Toolkit. This allows you to view your positions and performance (over time) versus a benchmark and other positions as well as your PnL development over time. Furthermore, the portfolio can be directly loaded in the core functionality of the Finance Toolkit as well making it possible to calculate all metrics and ratios for your portfolio (which is a time-weighted sum of all positions). The portfolio module is a standalone module and can be used as such by using from financetoolkit import Portfolio. Find the the full portfolio documentation here.
It is important to note that it requires a specific Excel template to work, see for further instructions the Getting Started guide here.
from financetoolkit import Portfolio
# Initialize the Portfolio module with your own dataset
portfolio = Portfolio(example=True, api_key="FINANCIAL_MODELING_PREP_KEY")
# Get an overview of all positions
portfolio.get_positions_overview()
The table below shows one of the functionalities of the Portfolio module but is purposely shrunken down given the >30 assets.
| Identifier | Volume | Costs | Price | Invested | Latest Price | Latest Value | Return | Return Value | Benchmark Return | Volatility | Benchmark Volatility | Alpha | Beta | Weight |
|---|
| AAPL | 137 | -28 | 38.9692 | 5310.78 | 241.84 | 33132.1 | 5.2386 | 27821.3 | 2.2258 | 0.3858 | 0.1937 | 3.0128 | 1.2027 | 0.0405 |
| ALGN | 81 | -34 | 117.365 | 9472.53 | 187.03 | 15149.4 | 0.5993 | 5676.9 | 2.1413 | 0.5985 | 0.1937 | -1.542 | 1.5501 | 0.0185 |
| AMD | 78 | -30 | 11.9075 | 898.784 | 99.86 | 7789.08 | 7.6662 | 6890.3 | 3.7945 | 0.6159 | 0.1937 | 3.8718 | 1.6551 | 0.0095 |
| AMZN | 116 | -28 | 41.5471 | 4791.46 | 212.28 | 24624.5 | 4.1392 | 19833 | 1.8274 | 0.4921 | 0.1937 | 2.3118 | 1.1594 | 0.0301 |
| ASML | 129 | -25 | 33.3184 | 4273.07 | 709.08 | 91471.3 | 20.4065 | 87198.3 | 3.8005 | 0.4524 | 0.1937 | 16.606 | 1.4407 | 0.1119 |
| VOO | 77 | -12 | 238.499 | 18352.5 | 546.33 | 42067.4 | 1.2922 | 23715 | 1.1179 | 0.1699 | 0.1937 | 0.1743 | 0.9973 | 0.0515 |
| WMT | 92 | -18 | 17.8645 | 1625.53 | 98.61 | 9072.12 | 4.581 | 7446.59 | 2.4787 | 0.2334 | 0.1937 | 2.1024 | 0.4948 | 0.0111 |
| Portfolio | 2142 | -532 | 59.8406 | 128710 | 381.689 | 817577 | 5.3521 | 688867 | 2.0773 | 0.4193 | 0.1937 | 3.2747 | 1.2909 | 1 |
In which the weights and returns can be depicted as follows:
Applying Econometric Techniques
The econometrics module provides regression, hypothesis testing, unit root and cointegration, Granger causality and panel data methods built on statsmodels and linearmodels. It requires the optional financetoolkit[econometrics] extra (pip install financetoolkit[econometrics]) and can be used via companies.econometrics.
# AAPL is the Toolkit's first ticker, so it's the default dependent ticker;
# every other ticker becomes the default independent set
companies.econometrics.get_ols(period="weekly")
Regressing Apple's returns on a mix of its chip suppliers, megacap peers and two unrelated names (Benchmark excluded) gives:
| Coefficient | Std. Error | t-Statistic | P-Value |
|---|
| Intercept | 0.0028 | 0.0017 | 1.6815 | 0.0943 |
| TSM | -0.0054 | 0.0523 | -0.1028 | 0.9182 |
| QCOM | 0.1432 | 0.0361 | 3.9717 | 0.0001 |
| SWKS | 0.2141 | 0.0484 | 4.4221 | 0.0000 |
| MSFT | 0.3036 | 0.0864 | 3.5144 | 0.0005 |
| GOOGL | 0.1448 | 0.0689 | 2.1015 | 0.0369 |
| AMZN | 0.0617 | 0.0529 | 1.1664 | 0.2448 |
| META | -0.0132 | 0.0389 | -0.3398 | 0.7343 |
| NVDA | -0.0024 | 0.0415 | -0.0575 | 0.9542 |
| XOM | -0.0291 | 0.0373 | -0.7799 | 0.4364 |
| PG | 0.2858 | 0.0707 | 4.0393 | 0.0001 |
And below each coefficient is shown with its 95% confidence interval, with stars marking how significant it is.
Only QCOM, SWKS, MSFT, GOOGL and PG come out statistically significant once every regressor is controlled for at once. The econometrics module covers 48 methods in total, including unit root tests (ADF, KPSS, Phillips-Perron), cointegration and Granger causality, panel data estimators (Fixed/Random Effects), causal inference (IV-2SLS, Difference-in-Differences, Regression Discontinuity, Propensity Score Matching, Synthetic Control) and time-series forecasting (ARIMA, VAR, VECM). Find the Getting Started guide here and the full econometrics documentation here.
MCP Server
The Finance Toolkit MCP Server exposes 500+ financial methods directly to any AI assistant that supports the Model Context Protocol (MCP). Ask questions in plain English — the AI fetches live financial data on your behalf, backed by the transparent, open-source calculation methods of the Finance Toolkit.
See an example of the Finance Toolkit MCP server in action in Claude Desktop below:
https://github.com/user-attachments/assets/96ad5288-d83d-4497-a345-1841c48c29d5
Remote server
Connect directly to the hosted server at https://financetoolkit.jeroenbouma.com/mcp. Nothing needs to be installed locally. On first connection your client opens an OAuth consent page asking for your FMP API key; enter it once and the server handles authentication from there.
| Client | Steps |
|---|
| Claude Desktop | Customize → Connectors → Add custom connector → paste the URL |
| Claude.ai | Customize → Connectors → Add custom connector → paste the URL |
| Claude Code | claude mcp add --transport http finance-toolkit https://financetoolkit.jeroenbouma.com/mcp |
| VS Code | Command Palette → MCP: Add Server → HTTP → paste the URL |
| Cursor | Settings → Features → MCP Servers → Add new → http → paste the URL |
| Windsurf | Settings → MCP Servers → Add Server → Remote/HTTP → paste the URL |
Local installation
Run the setup wizard — it locates your client's config file and writes the MCP entry automatically, including the API key:
uvx --from "financetoolkit[mcp]" financetoolkit-mcp-setup
For manual config, add the following to your client's MCP config file (e.g. 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" }
}
}
}
Alternatively, download the Finance Toolkit MCPB bundle and open it with Claude Desktop. An installation dialog will prompt for your FMP API key.
Questions & Answers
This section includes frequently asked questions and is meant to clear up confusion about certain results and/or deviations from other sources. If you have any questions that are not answered here, feel free to reach out to me via the contact details below.
How do you deal with companies that have different fiscal years?
For any financial statement, I make sure to line it up with the corresponding calendar period. For example, Apple's Q4 2023 relates to July to September of 2023. This corresponds to the calendar period Q3 which is why I normalize Apple's numbers to Q3 2023 instead. This is done to allow for comparison between companies that have different fiscal years.
Why do the numbers in the financial statements sometimes deviate from the data from FinancialModelingPrep?
When looking at a company such as Hyundai Motor Company (ticker: 005380.KS), you will notice that the financial statements are reported in KRW (South Korean won). As this specific ticker is listed on the Korean Exchange, the historical market data will also be reported in KRW. However, if you use the ticker HYMTF, which is listed on the American OTC market, the historical market data will be reported in USD. To deal with this discrepancy, the end of year or end of quarter exchange rate is retrieved which is used to convert the financial statements to USD. This is done to prevent ratio calculations such as the Free Cash Flow Yield (which is based on the market capitalization) or Price Earnings Ratio (which is based on the stock price) from being incorrect. This can be disabled by setting convert_currency=False in the Toolkit initialization. It is recommended to always use the ticker that is listed on the exchange where the company is based.
How can I get TTM (Trailing Twelve Months) and Growth metrics?
Most functions will have the option to define the trailing parameter. This lets you define the number of periods that you want to use to calculate the trailing metrics. For example, if you want to calculate the trailing 12-month (TTM) Price-to-Earnings Ratio, you can set trailing=4 when you have set quarterly=True in the Toolkit initialization. The same goes for growth metrics which can be calculated by setting growth=True. This will calculate the growth for each period based on the previous period. This also includes a lag parameter in which you can define lagged growth. Furthermore, you can also combine the trailing and growth parameters to get trailing growth. For example, set trailing=4 and growth=True for the Price-to-Earnings Ratio which will then calculate the TTM growth.
Does the Finance Toolkit retrieve the same data every time I run it?
No. Any data that comes from an external source (financial statements, historical prices, economic indicators, yield curves, news and so on) is cached automatically in a local SQLite database and reused on the next run, in the Toolkit as well as in the Economics, Fixed Income, Discovery and Portfolio modules. Anything the Finance Toolkit calculates itself, such as ratios, models and risk metrics, is never cached: it is always derived from that data on demand, so it reflects the latest version of the Finance Toolkit.
Cached data does not go stale. Each dataset is retrieved again once it may have changed: prices and financial statements after a day (prices only for the last week, since older bars no longer change), quotes after a minute, company profiles after a month and economic releases according to how often they are published. An answer that a source has no data, such as the ETF holdings of a company, is cached as well, while a failed request, such as a rate limit, is not.
The cache keeps track of what it already holds per ticker and per date range, which means changing a parameter does not throw the rest away:
- Repeating the same request retrieves nothing at all.
- Widening the period only retrieves the years that were missing.
- Adding a ticker only retrieves that one ticker.
The database lives in your user configuration directory, which is the same one the MCP server uses, so both share a single cache. You can choose where it is stored, or switch caching off:
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)
Setting the FINANCE_TOOLKIT_CACHE_ENABLED environment variable to 0 switches caching off by default everywhere, which suits environments where nothing should be written to disk, such as a continuous integration job. FINANCE_TOOLKIT_CACHE_DB moves the shared database to another file.
To see what is currently stored, use toolkit.get_cache_contents(). It reports the entries grouped by source and dataset:
| 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 |
The Finance Toolkit never clears the cache on its own, not even when its own internal structure changes. Removing data is always something you ask for explicitly with toolkit.clear_cache(), and it can be narrowed instead of wholesale:
# 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)
The source names match the ones used by the enforce_source parameter, so "FinancialModelingPrep" and "YahooFinance" mean the same thing in both places.
What is the "Benchmark" that is automatically obtained when acquiring historical data?
This is related to the benchmark_ticker parameter which is set to "SPY" (S&P 500) by default. This is important when calculating performance metrics such as the Sharpe Ratio or Treynor Ratio that require a market return. This can be disabled by setting benchmark_ticker=None in the Toolkit initialization.
Data collection seems to be slow, what could be the issue?
Generally, it should take less than 15 seconds to retrieve the historical data of 100 tickers. If it takes much longer, this could be due to reaching the API limit (the Starter plan has 250 requests per minute), due to a slow internet connection or due to unoptimized code. The Finance Toolkit collects data with a bounded pool of worker threads (10 by default, configurable through the FINANCETOOLKIT_MAX_WORKERS environment variable) over a shared connection, so it is recommended to initialize the Toolkit with all tickers you want to analyze at once rather than one at a time. If it is taking 10+ minutes consider having a look at this issue that managed to resolve the problem.
I work behind a corporate proxy and get "certificate verify failed" errors, how do I solve this?
Many corporate networks inspect encrypted traffic. The proxy opens every HTTPS connection on your behalf and presents a certificate signed by your company's own root certificate instead of the website's real one. Your browser trusts that root certificate because IT installed it on your computer, but Python does not: it checks certificates against its own list of public certificate authorities (the certifi package), which does not include your company's. The result is an error such as SSLError: certificate verify failed: self-signed certificate in certificate chain.
When a certificate cannot be verified, the Finance Toolkit first retries with your operating system's certificate file, where Python can find one (usually on Linux, not on Windows). If that fails as well, what happens next depends on whether the request carries an API key:
- Requests without an API key, such as those to the ECB, Eurostat or the BIS, are retried without verifying the certificate. A warning is logged when this happens.
- Requests with an API key, such as those to FinancialModelingPrep and FRED, are not retried without verification. The key is part of the web address, so anyone who can intercept an unverified connection could read it and use your subscription. The request fails with an error that explains the options below.
The recommended solution is to tell Python to trust your company's root certificate, so every connection stays verified:
-
Obtain the root certificate as a .pem (or .crt) file. Your IT department can usually provide it. You can also export it from your browser by opening the certificate details of any HTTPS website and exporting the top certificate in the chain ("Base-64 encoded" on Windows).
-
Combine it with Python's public certificates. The next step replaces Python's list rather than adding to it, so without the public certificates every connection that does not go through the proxy would fail:
# Prints the location of Python's public certificates
python -c "import certifi; print(certifi.where())"
# macOS and Linux: combine both into one file
cat /path/printed/above/cacert.pem /path/to/company-root.pem > ~/combined-certificates.pem
On Windows you can open both files in a text editor and paste the company certificate at the end of a copy of cacert.pem.
-
Point REQUESTS_CA_BUNDLE to the combined file before using the Finance Toolkit:
# macOS and Linux, e.g. in ~/.bashrc or ~/.zshrc
export REQUESTS_CA_BUNDLE=~/combined-certificates.pem
# Windows (PowerShell), for every window opened afterwards
setx REQUESTS_CA_BUNDLE "C:\Users\you\combined-certificates.pem"
setx does not change the window it runs in, so open a new terminal (or restart your editor) afterwards.
Or set it within Python, before the first request:
import os
os.environ["REQUESTS_CA_BUNDLE"] = "/path/to/combined-certificates.pem"
from financetoolkit import Toolkit
When you use the MCP server, add the variable to the env section of the server in your AI assistant's configuration instead.
Alternatively, if your company's root certificate is already installed in your operating system (which is usually the case on managed Windows and macOS computers), the truststore package lets Python use the operating system's certificates directly. Install it with pip install truststore and run import truststore; truststore.inject_into_ssl() at the start of your script.
If none of this is possible, you can accept the risk and allow requests with an API key to be sent without verification by setting FINANCETOOLKIT_ALLOW_UNVERIFIED_SSL=1 in the same way as above. Only do so on a network you trust: the connection is then encrypted to whoever answers it, which may not be the website you think you are talking to, and your API key is readable to them.
Are you part of FinancialModelingPrep?
No, I am not. I've merely picked them as the primary data provider given that they have a generous free tier and fair pricing compared to other providers. Therefore, any questions related to the data should go through their contact form. When it comes to any type of ratios, performance metrics, risk metrics, technical indicators or economic indicators, feel free to reach out to me as this is my own work.
Contributing
First off all, thank you for taking the time to contribute (or at least read the Contributing Guidelines)! 🚀
Find the Contributing Guidelines here.
The goal of the Finance Toolkit is to make any type of financial calculation as transparent and efficient as possible. I want to make these type of calculations as accessible to anyone as possible and seeing how many websites exists that do the same thing (but instead you have to pay) gave me plenty of reasons to work on this.
Mentions
The Finance Toolkit has been mentioned in various blogposts, research papers, newsletters and social media. Below is a list of some of the mentions that I am aware of. If you have any other mentions, feel free to reach out to me so I can add them to this list.
Blogposts
Research
Newsletters & Social Media
Contact
If you have any questions about the Finance Toolkit or would like to share with me what you have been working on, feel free to reach out to me via:
If you'd like to support my efforts, either help me out by contributing to the package or Sponsor Me.