Documentation

These pages document the Finance Toolkit, 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 calculation method. Each class has an introduction page like this one, and the sidebar leads to a page for every function that shows how to use it through the Finance Toolkit MCP in an AI assistant and in Python. The Python examples are also embedded in the code. For simplicity sake, only the controller modules are included here given that the models themselves should be relatively straightforward. Make sure to also have a look at the Getting Started section below and the one that opens every module page.

The Toolkit Module is a collection of functions that collect and parse data, including historical data, fundamental data (balance, income and cash flow statements) and metrics from Financial Modeling Prep such as enterprise values, company profiles and more. From this module you can access all related sub-modules.

Every function of the Toolkit module has its own page showing how to use it with the MCP and in Python. Pick one from the sidebar on the left.Every function of the Toolkit module has its own page showing how to use it with the MCP and in Python. Pick one from the documentation menu.

Use it in Claude, ChatGPT or another AI assistant through the Finance Toolkit MCP, or install the Python package:

pip install financetoolkit -U

Getting Started

The Finance Toolkit computes 500+ financial ratios, indicators and models from the underlying data with one transparent formula each, so a margin or a Sharpe ratio means the same thing for every company and every period. This section covers the basics: loading a set of companies, retrieving their prices and financial statements, the options that work across nearly every function, and the company data beyond the statements. Each module’s own documentation page opens with a Getting Started section of its own.

Data and API Keys

Most data comes from Financial Modeling Prep, which needs an API key. The free plan allows 250 requests a day, five years of history and companies listed on US exchanges; the paid plans give 30+ years of annual and quarterly statements. You can get a key through this link, which also gives 15% off the paid plans and supports the project. Without a key, or when a request is outside your plan, the Toolkit falls back to Yahoo Finance; set enforce_source="FinancialModelingPrep" to switch that off.

Loading the Toolkit

Everything starts with a Toolkit instance for one or more tickers. The data is retrieved once and kept, so every ratio, model and indicator afterwards is computed from the same statements and prices without asking the data provider again. Annual statements are the default; add quarterly=True for quarterly statements (a paid Financial Modeling Prep plan).

To load Apple, Microsoft, Alphabet and Amazon from 2005 onwards:

from financetoolkit import Toolkit

API_KEY = "FINANCIAL_MODELING_PREP_KEY"

companies = Toolkit(
    ["AAPL", "MSFT", "GOOGL", "AMZN"], api_key=API_KEY, start_date="2005-01-01"
)

Every example below uses this companies instance.

Historical Data

get_historical_data returns open, high, low, close, adjusted close, volume, dividends, returns and cumulative returns for every ticker, plus the benchmark (the S&P 500 through SPY by default; change it with benchmark_ticker). The period can be daily (the default), weekly, monthly, quarterly or yearly.

To retrieve daily, yearly and quarterly prices:

# Daily prices for every company and the benchmark
daily = companies.get_historical_data()

# One row per year
yearly = companies.get_historical_data(period="yearly")

# The cumulative return per quarter
cumulative_returns = companies.get_historical_data(period="quarterly")["Cumulative Return"]

The columns hold two levels, the field and the ticker, so daily["Close"] gives the closing prices of all companies and daily.xs("AAPL", axis=1, level=1) everything for Apple. The cumulative returns start at 1, so a value of 10 means the investment grew tenfold:

When tickers trade on different exchanges or in different currencies, it helps to check what each one is. To see the currency, exchange and listing details of every ticker:

companies.get_historical_statistics()

Which shows, among other fields:

Financial Statements

The balance sheet, income statement and cash flow statement come back in one standardized layout for every company: the rows are the ticker and the line item, the columns the fiscal years (or quarters with quarterly=True). Because the line items have the same names for every company, comparing Apple’s equity with Amazon’s is a matter of selecting a row.

To retrieve the three statements:

balance_sheet = companies.get_balance_sheet_statement()
income_statement = companies.get_income_statement()
cash_flow_statement = companies.get_cash_flow_statement()

# The balance sheet of Amazon only
balance_sheet.loc["AMZN"]

# One line item for every company
equity = balance_sheet.xs("Total Shareholder Equity", level=1)

The last line selects total shareholder equity for all four companies, which plotted per fiscal year gives:

Growth, Trailing, Rolling and Z-Scores

A handful of parameters work across nearly every function in the Toolkit, from the statements to the ratios, risk and performance metrics.

growth=True returns the period-over-period change instead of the value itself. To get the revenue growth of each company:

income_statement_growth = companies.get_income_statement(growth=True)

income_statement_growth.loc[:, "Revenue", :]

Which gives the year-over-year revenue growth, one company per tab, from 2008:

By default growth is measured against the previous period. lag changes that, and a list of lags returns each of them side by side, e.g. the growth over one, two and three years. To get the growth of every income statement item over three lags:

companies.get_income_statement(growth=True, lag=[1, 2, 3])

Three more parameters turn a single number per period into something more useful:

• trailing sums or averages a metric over the last N periods. On quarterly data trailing=4 gives the trailing twelve months (TTM); on annual data, as here, it covers four years.
• standardize=True converts the values into a Z-Score: the number of standard deviations a value is from that company’s own historical mean. It makes metrics on very different scales comparable and shows when a reading is unusual for that company.
• rolling calculates a metric over a sliding window, which turns a metric into a time series of itself. It is available in the Risk, Performance and Economics modules.

To calculate a trailing net profit margin, a standardized operating margin and a rolling 12-month beta:

# Trailing: the net profit margin over the last four periods
companies.ratios.get_net_profit_margin(trailing=4)

# Standardize: the operating margin as a Z-Score
companies.ratios.get_operating_margin(standardize=True)

# Rolling: the beta against the S&P 500 over the last 12 months
companies.performance.get_beta(period="monthly", rolling=12)

When plotted, one tab per parameter: the trailing net profit margin with its path since 2015, the operating margin as a Z-Score per company and year (blue above the company’s own average, pink below), and the rolling beta of Apple and Alphabet with the market’s beta of 1 dashed:

Earnings and ESG Scores

Beyond the reported figures, the Toolkit also retrieves the earnings calendar: for every quarterly report, the earnings per share and revenue next to the analyst consensus beforehand. The ESG scores give the environmental, social and governance scores per year, and a combined ESG score.

To retrieve both:

earnings_calendar = companies.get_earnings_calendar()

esg_scores = companies.get_esg_scores()

When plotted, the revenue surprise over the last eight quarters (the reported revenue against the consensus estimate) and, in the second tab, the combined ESG score per company and year on a scale from 0 to 100:

Revenue Segmentation

Most large companies also report their revenue split by product line and by region. The Toolkit returns both segmentations with the segment names as each company reports them, so they differ per company and can change over the years when a company reorganises its reporting.

To retrieve the product and geographic segmentation, and select Apple’s:

product_segmentation = companies.get_revenue_product_segmentation()
geographic_segmentation = companies.get_revenue_geographic_segmentation()

product_segmentation.loc["AAPL"]

When plotted, Apple’s revenue per product line since 2019, the first year it reported all five, and per region since 2015:

The earnings calendar, dividend calendar, company profiles, quotes, news and more are available in the same way; the sidebar lists every function.