Vintage README

Free financial data exists and is scattered across twenty APIs with twenty shapes. Everyone rebuilds the same glue, badly, and quietly ends up backtesting on restated figures and survivor biased universes.

Vintage is that glue, written once, served over MCP. It hosts no data. It connects, normalizes, and serves structured financial data from the web.

A research terminal that costs $0 and won't lie to you about your Sharpe.

rezasoleymanifar.github.io/vintage

What people use it for

_{Two of four scenes — see the full reel on the site.}

Install

Claude Code

claude mcp add vintage -s user -- uvx vintage-mcp

Claude Desktop / any MCP client — add to your config file:

{
  "mcpServers": {
    "vintage": {
      "command": "uvx",
      "args": ["vintage-mcp"]
    }
  }
}

_{Claude Desktop config lives at %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS). Restart the app afterwards. MCP servers load once at startup.}

Needs uv. If you'd rather use pip: pip install vintage-mcp and set the command to vintage.

Optional configuration

Everything works with zero configuration. These make it work better:

Set them under "env" in the same config block:

{
  "mcpServers": {
    "vintage": {
      "command": "uvx",
      "args": ["vintage-mcp"],
      "env": {
        "VINTAGE_USER_AGENT": "Jane Quant jane@example.com",
        "FRED_API_KEY": "..."
      }
    }
  }
}

Your key stays in this file. It is read by the server process and is never passed through the model or written into the conversation.

Use it as a library

The same data, without the server. Everything is synchronous and returns pandas, including inside Jupyter where a loop is already running.

import vintage as v

v.prices("AAPL", start="2020-01-01")          # daily prices, with known_at
v.panel(["AAPL", "MSFT", "JNJ"])              # dates x tickers
v.fundamentals("AAPL", "us-gaap:Assets", as_of="2020-01-01")
v.restatements("AAPL", "us-gaap:Assets")      # periods reported twice, differently
v.factors("ff3")                              # Ken French, wide
v.macro("DGS10", as_of="2008-09-15")          # ALFRED first-release vintage
v.claim("Mom12m")                             # what the paper claimed
v.claims(price_only=True)                     # the 56 replicable with free data
v.crypto("BTC-USD")
v.short_volume("AAPL")
v.sentiment("wallstreetbets")

known_at is kept as a column on every frame rather than dropped for tidiness — losing it is how a point-in-time dataset quietly becomes an ordinary one. Pass as_of and rows published after that date are gone before you see them.

Try it

Once installed, ask your assistant:

"What was Apple's total assets as of January 2020 — and has it been restated since?"

"Backtest 12-1 momentum on the Dow 30 since 2010."

"Now try short-term reversal instead. Did the alpha survive?"

The third question is the one that matters. Every answer carries the worst held-out path next to the headline Sharpe.

The two dates

Every value carries both:

• observed_at — what period the number describes
• known_at — when it first became public

A backtest may only use rows whose known_at precedes the trade date. That is structural, not a setting: the panel is indexed on known_at, so any slice of it is automatically point-in-time. There is no flag to turn it off.

Sources that cannot supply an honest known_at are flagged UNKNOWN_VINTAGE rather than given a fabricated date.

Six ways yesterday's data quietly changed

• Lag — the number is true in December, published in February.
• Restatement — the company says "oops, wrong" and changes last year's figure.
• Revision — the government keeps fixing old jobs and inflation numbers, for years.
• Survivorship — dead companies get deleted; only the winners are still listed.
• Membership — today's S&P 500 list is not the list from 2005.
• Price adjustment — splits and dividends silently rewrite every price before them.

All six say the same thing: the data you have today is not what people saw back then.

Six verbs

Source is a parameter, never a separate tool. Twenty more sources adds zero tools.

Plus status for cache size, keys, and how many specs you have tried.

Backtesting methodology

• Deflated Sharpe (Bailey & López de Prado, 2014) accounting for every spec tried this session
• Costs always charged on turnover. There is no zero-cost mode
• A standing survivorship warning, because the universe is a list of names that exist today

Vintage implements the backtest-validation literature rather than inventing its own statistics. Execution realism is a different problem, already solved by LEAN and Nautilus Trader — Vintage runs before that, at the stage where most ideas should die.

Citations are references, not endorsements — none of these authors is affiliated with Vintage. Anything marked planned is not in the code yet, and the backtest response says so at runtime rather than in the footnotes.

Where the data comes from

A century of market history, twenty-two sources, and twenty of them need no key at all. The Fama-French factors start in July 1926 and the SEC filing stream runs to this morning — Vintage covers both ends from the same six verbs.

Most of these are the primary source — not a reseller, not a scraper. The filings come from the regulator that receives them, the macro series from the central bank that publishes them, and the factors from the university that computes them.

@remove all emojis and just print list of soruceswith icons for them.

COVERAGE.md is the full field-by-field catalogue — every prefix, every dataset, every signal, with measured coverage spans. It is generated from the registry, so it cannot drift from the code.

Counts current as of August 2026. Vintage redistributes none of this — each upstream source keeps its own terms.

Cache

Gzipped JSON in ~/.cache/vintage, tiered by how mutable the data is: closed periods never refetch, academic datasets monthly, current fundamentals daily, prices per session. An hour of conversation is roughly 20 upstream calls.

Known gaps

Stated plainly, because the alternative is shipping a bad substitute:

Data:

• Survivorship — universes are current-listing only. Form 25 delistings are the next build and the backtester warns until then.
• Analyst estimates — no free source exists.
• Historical options chains — paid everywhere.
• Point-in-time index membership — licensed by S&P and MSCI.

Engine — the backtester is vectorized and cross-sectional, which is a rung below an event-driven simulator:

• No purging or embargo — overlapping label windows can leak across a train/test split (López de Prado, AFML ch. 7). Deflation catches selection bias, not leakage.
• No market impact — costs are a flat charge on turnover, so large-notional results are optimistic.
• No PBO — deflated Sharpe covers multiple testing; the Probability of Backtest Overfitting via combinatorially symmetric cross-validation would be the stronger test.
• Trial count is session-scoped and resettable — reset_trials=True zeroes it mid-conversation. Deliberate: the correction only applies to repeated attempts at one question, and the engine cannot tell those from unrelated ones.
• Sharpe is per observation, not annualized — that is the frequency the deflation is defined at, and the response says so.

Development

git clone https://github.com/RezaSoleymanifar/vintage
cd vintage
uv sync --group dev
uv run pytest

smoke_test.py exercises all six verbs against the live sources — useful before a release, and it needs network.

License

MIT. Vintage redistributes no data; each upstream source keeps its own terms.

_{mcp-name: io.github.RezaSoleymanifar/vintage}