Open-source project
JerBouma/FinanceDatabase avatar
JerBouma/FinanceDatabase

FinanceDatabase: a 303,261-symbol CSV catalog that finds tickers but holds no prices

This is a database of 300.000+ symbols containing Equities, ETFs, Funds, Indices, Currencies, Cryptocurrencies and Money Markets.

9,641 stars1,005 forksPythonMIT

At a glance

What is it?
JerBouma/FinanceDatabase is an MIT-licensed symbol catalog with a Python API and an MCP server. It is good at showing which equities, ETFs and funds exist in a sector or country, and it gives you nothing to analyze on its own once the question involves a price or a fundamental.
Who is it for?
FinanceDatabase is the right tool if you need to enumerate what exists: every listed company in an industry, every ETF from an issuer, the ISIN behind a ticker, and you want that list free, without an API key, in CSV files you can edit. It is the wrong tool if you expect prices, fundamentals or exact market capitalization, because it stores none of them and its market_cap column is a size label.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 5 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 19, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • JerBouma/FinanceDatabase9,641 ★ · +218
Star history
Repository2026-10-072026-11-19
JerBouma/FinanceDatabase9.4k9.6k

218 Stars in the last 43 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

303,261 symbols kept in CSV files anyone can edit

FinanceDatabase is a Python package and a data set in the same repository. The financedatabase/ directory holds the code and database/ holds the data, which is stored as CSV files that anyone can read and correct. That choice is the whole growth model: the author describes the database as one that grows and improves through community edits, and CONTRIBUTING.md sits at the top level for that purpose.

The statistics table at the top of the README is regenerated weekly by scripts/update_readme_stats.py from database/. At the latest count it lists 303,261 symbols: 121,559 equities on 87 exchanges, 32,047 ETFs from 636 issuers, 57,761 funds from 1,534 fund families, 82,370 indices in 42 categories, 2,516 currencies, 5,783 cryptocurrencies covering 672 coins and 12 quote currencies, and 1,225 money market funds from 131 fund families. Equities are spread over 11 sectors, 75 industries and 118 countries.

The license is MIT, so the CSV files can be reused in other projects. The repository is not archived. The last push to main was on 1 November 2026, and releases 2.5.0 and 2.5.1 shipped on 10 and 12 October 2026, following 2.4.0 on 2 June 2026.

It will not give you a price or a balance sheet

The author states plainly that the aim is not to provide up-to-date fundamentals or stock data. A row tells you that a ticker exists, where it is listed, which currency it trades in and how it is classified. It does not tell you what the stock closed at, what the company earned, or what an ETF holds today. If you install FinanceDatabase hoping for a free replacement for a market data feed, you end up with a well organized list of tickers and no numbers to compute anything with.

The intended companion is the Finance Toolkit, a separate project by the same author. The workflow is to filter FinanceDatabase down to the products you care about, for example the equities in the Semiconductors & Chip Equipment industry listed in the Netherlands, and then feed those tickers into the Finance Toolkit to pull fundamentals and run a competitive analysis. FinanceDatabase is the discovery layer in that pair. Its job is answering what products exist in a country, sector or industry, including ones that are hard to find by searching the web. As soon as your question involves a number, plan for a second dependency and the data source behind it.

Initialize each asset class once, because that call downloads it

Installation is one pip command, with -U upgrading a copy you already have:

code
pip install financedatabase -U

Then, in Python:

python
import financedatabase as fd

equities = fd.Equities()

No API key is needed at any point. Each asset class is downloaded once and then cached locally, which has two practical effects. First, the first time you create an asset class object the machine needs network access to fetch that data. Second, creating the object is the step you do not want to repeat: the README says initialization is only required once per asset class and that you should save it to a variable so later queries run much more quickly. In a notebook, keep the equities object in a cell you run once rather than rebuilding it inside every analysis cell.

The cache location is configurable. The Docker files set FINANCEDATABASE_CACHE_DIR to /data/financedatabase, and the README sends readers to its Questions & Answers section for the details of how the cache behaves. The Dockerfile adds that, in the server setup, the cached database is checked for updates at most once a day.

What a row returned by select() contains

The basic query selects everything in an asset class:

python
import financedatabase as fd

# Initialize the Equities database
equities = fd.Equities()

# Select all equities
equities.select()

The sample output in the README is trimmed to five rows and a subset of columns, and even that subset shows what the data is for. Each equity row carries symbol, name, currency, sector, industry, exchange, market, country, market_cap and isin. Apple appears as AAPL with exchange NMS and market NASDAQ Global Select. ASML Holding is ASML.AS on AMS, Euronext Amsterdam. Toyota is 7203.T on JPX, the Tokyo Stock Exchange. Nestle is NESN.SW on EBS, the SIX Swiss Exchange, and SAP is SAP.DE on GER, which the market column names XETRA.

So the symbol carries an exchange suffix, the exchange column holds a short code, and the market column holds the readable venue name. The isin column is the useful one for joining against other systems that do not share the same ticker format, for example US0378331005 for Apple or NL0010273215 for ASML. For the full set of columns and the complete output of each query, the repository ships a Getting Started notebook in examples/.

market_cap is a size label, and the counts are a weekly snapshot

In the sample rows, market_cap reads Mega Cap. It is a classification bucket, not a value in dollars or euros. You can filter for mega caps or exclude them, but you cannot sort companies by capitalization, weight a portfolio, or compute an index from this column. Anyone building a screener that depends on actual size has to fetch that figure from somewhere else.

The headline numbers need the same care. The statistics block is regenerated weekly from database/, and edits made between its markers are overwritten by the script. The counts quoted above describe the repository at one point in time. The copy cached on your machine reflects whenever it was last downloaded, so totals you compute locally can differ from the README table.

Community editing has a cost too. Because the classifications live in CSV files that people correct by hand, a ticker filed under the wrong industry or country stays that way until someone edits the file. If your analysis groups companies by sector or industry, spot check the rows that drive your result instead of treating the classification as authoritative. The sector names, such as Information Technology, Consumer Discretionary and Consumer Staples, are this database's own scheme, and you will need a mapping if your internal taxonomy uses different labels.

The MCP server: a hosted URL or a one-line local setup

FinanceDatabase is also exposed as an MCP server, registered under the name io.github.JerBouma/financedatabase, so Claude, Copilot, Cursor, Windsurf or any other MCP-compatible client can query all of the symbols without writing Python. There are two ways to connect.

The hosted option is a URL, https://financedatabase.jeroenbouma.com/mcp, with nothing to install and no API key. The local option runs the setup tool through uvx, which also writes your client configuration for you:

code
uvx --from "financedatabase[mcp]" financedatabase-mcp-setup

The mcp extra is what pulls in the server dependencies, so a plain pip install of the library does not give you the server. Manual configuration steps for local clients are on the MCP Server Documentation page on jeroenbouma.com, and the latest GitHub release also carries a financedatabase.mcpb file. The repository includes server.json and glama.json at the top level for registry listings.

The tradeoff between the two is about where your queries go. With the hosted endpoint, every question your assistant asks is sent to the author's server. The compose file notes that usage statistics are enabled on the hosted server through a .env file, and the repository contains a PRIVACY.md. Read it before pointing a client that handles sensitive work at the public endpoint; if that is a problem, run the server yourself.

Self-hosting the MCP server with the bundled Dockerfile

The Dockerfile and docker-compose.yml exist to run the MCP server on localhost or on your own server. The image starts from python:3.12-slim, installs uv, and runs uv sync --frozen --extra mcp --no-dev twice, first for dependencies only and then for the package, so the dependency layer stays cached unless pyproject.toml or uv.lock change. Bringing it up is:

code
docker compose up -d

The server then listens on http://localhost:8000/mcp. The compose file sets MCP_TRANSPORT to streamable-http, MCP_HOST to 0.0.0.0 and MCP_PORT to 8000, and a health check calls /health every 30 seconds with three retries.

Two variables matter for privacy. FD_MCP_ANALYTICS defaults to 0, and only when set to 1 does the server record usage statistics, served at /stats and stored in the cache volume. FD_MCP_SECRET_KEY is an optional secret that users are hashed with; leave it empty and the server generates one and keeps it in the volume.

That volume, fd_cache mounted at /data/financedatabase, holds the downloaded database so restarts do not fetch it again. Delete it and you lose both the cache and the generated secret, which means a full re-download and different user hashes. Nothing in the compose file configures authentication, and the host binding is 0.0.0.0, so on a machine reachable from outside, put port 8000 behind your own access control.

Editorial conclusion

FinanceDatabase is the right tool if you need to enumerate what exists: every listed company in an industry, every ETF from an issuer, the ISIN behind a ticker, and you want that list free, without an API key, in CSV files you can edit. It is the wrong tool if you expect prices, fundamentals or exact market capitalization, because it stores none of them and its market_cap column is a size label. Before building on it, check that the classification scheme matches yours, budget for a second data source such as the Finance Toolkit for anything numeric, and, if you plan to use the hosted MCP endpoint, read PRIVACY.md first.

Frequently asked questions

What is the best database for financial data, and where does FinanceDatabase fit?

FinanceDatabase is a free, MIT-licensed catalog of 303,261 symbols for finding which equities, ETFs, funds, indices, currencies, cryptocurrencies and money markets exist. It does not provide prices or fundamentals; its author pairs it with the Finance Toolkit for that.

Who uses financial data from FinanceDatabase?

The author built FinanceDatabase as a private investor who wanted to see which companies and ETFs exist beyond the well-known names. Its MCP server also lets people using Claude, Copilot, Cursor or Windsurf query it without writing code.

Where can I get free financial data such as FinanceDatabase?

FinanceDatabase installs with pip install financedatabase -U and needs no API key. The CSV files are in the JerBouma/FinanceDatabase GitHub repository, and a hosted MCP endpoint is at https://financedatabase.jeroenbouma.com/mcp.

What is a financial database like FinanceDatabase?

FinanceDatabase is a set of CSV files that classify each symbol by fields such as sector, industry, exchange, market, country, currency, market cap class and ISIN. It describes which products exist rather than storing market prices.

Official sources

  1. JerBouma/FinanceDatabase on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/jerbouma-financedatabase.svg)](https://hysenlabs.com/projects/jerbouma-financedatabase)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/jerbouma-financedatabase.svg)](https://hysenlabs.com/projects/jerbouma-financedatabase)

Was this useful?