Finance Toolkit: 500 financial metrics with the arithmetic left visible

Eight price-to-earnings figures for one company on one day

The README opens with a problem rather than a feature list. On the sixth of May 2023, the Price-to-Earnings ratio for Microsoft is reported as 28.93 by Stockopedia, 32.05 by Morningstar, 32.66 by Macrotrends, 33.09 by Finance Charts, 33.66 by Y Charts, 33.67 by the Wall Street Journal, 33.80 by Yahoo Finance and 34.4 by Companies Market Cap. All eight are correct, because each applies a different definition, and the definitions are frequently hidden behind a paid subscription.

That is the design constraint. The project presents itself as a toolkit of more than 500 financial methods written down in the simplest way possible, with the intent that the calculation method is transparent rather than asserted. The README links to `financetoolkit/ratios/valuation_model.py` as proof of that claim, and the topics list backs it up with valuation, financial statements, fundamental analysis, factor analysis and quantitative finance.

The practical consequence is a different relationship with your numbers. Instead of accepting a provider's ratio, you can compute it from statements you have inspected and see exactly which denominator was used. That matters most for the metrics where providers genuinely disagree, and it matters least for the ones everybody computes the same way.

What the dependency list reveals about where the data comes from

`pyproject.toml` names `yfinance` among the runtime dependencies, alongside pandas 3.0 or newer, scikit-learn 1.6 or newer, requests, openpyxl and pyyaml. That single entry answers the sourcing question: statements and prices are fetched from Yahoo Finance, and everything above that layer is local computation.

Two optional dependency groups extend the picture. The `econometrics` extra pulls in statsmodels 0.14 and linearmodels 6.0, which is consistent with the v2.2.0 release notes describing a new Econometrics module of 48 methods covering regression, panel data, causal inference, unit root and cointegration tests, Granger causality, diagnostics and forecasting, all delegated to those libraries rather than implemented from scratch. The `mcp` extra depends on the econometrics extra, since the MCP server exposes every module including that one.

The Python floor is `>=3.11, <3.16`, with classifiers for 3.11 through 3.15, a narrower range than the sibling FinanceDatabase package. The license is MIT and the project is classified as Development Status 5, Production/Stable.

The module notebooks in examples tell you what actually exists

The repository carries a numbered notebook per module, which is the most efficient way to see the real API: `Finance Toolkit - 1. Getting Started.ipynb` first, then Discovery, Ratios, Models, Options, Technicals, Risk, Performance, Economics, Fixed Income, Portfolio and Econometrics, plus one on using external datasets and a README Examples notebook that mirrors the documentation.

That list is more informative than a feature bullet list because it tells you where the boundaries are. There is a dedicated Economics module and a dedicated Technicals module, so macro series and price-derived signals are separate concerns from company fundamentals. Fixed Income and Options are both present, and Portfolio appears with its own notebook even though the README's opening argument is about individual equity ratios.

For learning the library, the Getting Started notebook is the entry point and the module notebooks are the reference. The repository also ships `Finance Toolkit - MCP Demo.mp4` and a demo gif, so the MCP path is documented visually rather than only in prose.

Deploying the MCP server on port 8000

The project is exposed to LLM tooling through the Model Context Protocol, and the packaging supports it properly rather than as an afterthought. A `mcp` extra, a `financetoolkit-mcp` console command, a `server.json`, a `glama.json`, a downloadable MCP bundle attached to releases and links to Smithery and Glama are all present in the repository.

For a self-hosted deployment the Dockerfile is short and shows the intended runtime. It builds from `python:3.12-slim`, installs uv, and syncs only the mcp extra with development dependencies excluded:

FROM python:3.12-slim

WORKDIR /app

RUN pip install uv

COPY pyproject.toml uv.lock README.md ./
RUN uv sync --frozen --extra mcp --no-dev

The compose file then binds the port and passes the secret through the environment, and it declares a named volume for the cache so it survives container replacement:

services:
  finance-toolkit-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      MCP_TRANSPORT: streamable-http
      MCP_PORT: "8000"
    volumes:
      - ft_cache:/root/.config/financetoolkit

Note the entry command and the health check that go with it: the container runs `uv run financetoolkit-mcp` and probes `/health` on port 8000 every 30 seconds. The `FT_MCP_SECRET_KEY` variable comes from your own environment rather than a baked-in value, and the compose file notes the server is also already hosted at financetoolkit.jeroenbouma.com/mcp if you would rather not run it yourself.

Why the v2.2.0 cache rewrite matters for repeated calls

The v2.2.0 release notes, published 2026-08-18, describe three incompatible caching mechanisms replaced by a single incremental, range-aware SQLite cache that knows what it holds per ticker and per date range. Widening a period retrieves only the missing years, and adding a ticker retrieves only that ticker. The notes also record a real correctness bug in the old cache, which could silently overwrite the tickers and dates you asked for with whatever an earlier cached run had used.

That second point is the one to sit with. A cache that returns data for the wrong instrument is worse than no cache, because it fails quietly. If you are upgrading from an earlier version, invalidate the old cache directory rather than carrying it forward.

Two other cross-cutting features arrived in v2.1.4. Most `get_` methods accept `rolling` and `trailing` parameters, so a snapshot metric can be computed over a sliding window instead of returning one value per reporting period. And `standardize=True` converts raw values into deviations from their own historical mean, which makes metrics on different scales comparable. The same release fixed a case-mismatch bug that was silently zeroing out diluted EPS, and v2.1.3 fixed a rolling window being applied on the ticker axis instead of the date axis.

Where the arithmetic stops and the data provider begins

The honest comparison is with what you would otherwise use. A commercial terminal gives audited statements, intraday prices, analyst estimates and a support desk, at a cost that puts it outside an individual budget. A hosted API such as a financial data SaaS gives clean JSON and a billed quota. Raw scraping code gives you full control and full responsibility.

Finance Toolkit sits between the last two. It wins on transparency and on cost, and it loses on data quality guarantees, because inheriting yfinance means inheriting its coverage gaps, its symbol mapping and whatever a free endpoint decides to return. The distinction the README insists on, a transparent method versus an opaque one, is real and worth having, but a transparent calculation over incomplete statements is still an incomplete answer.

The last push to the repository was on 2026-09-10, three weeks after v2.2.0, so the release line is moving and the changelog documents real defects rather than only new features. Read the module notebook for the module you care about, check the file behind the formula, and treat every result as reproducible arithmetic on someone else's data rather than as a number of record.

Editorial conclusion

Finance Toolkit earns its place when a metric's definition matters more than its availability, which is exactly the case the README argues with eight different price-to-earnings figures for Microsoft on the same day. The formulas live in files you can read, the cache is incremental rather than a stale blob, and the module notebooks in `examples/` show real calls rather than pseudocode. It will not replace a terminal for intraday prices or analyst estimates, and it inherits whatever yfinance returns, so treat the output as reproducible arithmetic rather than as audited data. Start with the Ratios notebook, then read `financetoolkit/ratios/valuation_model.py`, because that file is the argument the whole project rests on.

Frequently asked questions

Official sources

1. JerBouma/FinanceToolkit on GitHub
2. License: MIT
3. Project website
4. README
5. Releases