Vintage

What Vintage MCP server does

Vintage MCP server provides a common interface for structured financial data gathered from multiple public sources. It does not store its own financial dataset; instead, it connects to sources on the web, normalizes their formats, and serves the results through MCP. The project also exposes the same data access patterns as a Python library that returns pandas objects.

The central distinction is between two dates attached to a value. observed_at identifies the period described by the value, while known_at records when that value first became public. Queries can use as_of to exclude information that was not yet available at a selected historical date. When a source cannot provide a reliable publication date, Vintage marks the vintage as UNKNOWN_VINTAGE rather than fabricating one.

How it works

Source selection is passed as a parameter instead of creating a separate tool for each provider. The main operations are:

• resolve: Converts an identifier into the entity key used by other requests.
• discover: Searches catalogs across the available sources using plain-language terms.
• fetch: Retrieves fields from a source, including historical filtering with as_of.
• events: Returns a filing timeline with public timestamps.
• backtest: Evaluates a cross-sectional signal and returns returns, costs, and held-out paths.
• benchmark: Compares supplied returns with published factors for correlation and alpha.
• status: Reports cache size, configured keys, and the number of specifications tried.

The backtest workflow uses a panel indexed by known_at, so a historical slice cannot use data that had not yet been released. Turnover costs are always applied. The reported Sharpe calculation includes a deflation adjustment based on the number of specifications tried in the current session. A survivorship warning is also maintained because a universe made from currently existing names may exclude companies that disappeared.

Setup and configuration

The documented local installation uses uvx vintage-mcp, and the package can also be installed with pip, after which the command is vintage. A compatible MCP client can launch it over standard input/output. Claude Desktop configuration uses a server entry with command set to uvx and args set to ['vintage-mcp']; the application must be restarted after configuration changes.

No configuration is required for basic operation. Optional environment variables are available for particular data sources and local behavior:

• VINTAGE_USER_AGENT supplies contact information requested by SEC EDGAR.
• FRED_API_KEY enables FRED access to macroeconomic series with first-release vintages; the key is available free from FRED.
• VINTAGE_CACHE_DIR changes the cache location, which otherwise defaults to ~/.cache/vintage.

Tools and capabilities

The Vintage MCP server covers examples such as prices, security panels, company fundamentals, restatements, Ken French factors, macroeconomic series, crypto data, short volume, and WallStreetBets sentiment. The README identifies public sources including SEC EDGAR, Form 13F, STOCK Act disclosures, FRED, ECB, US Treasury, BLS, BEA, CFTC, CBOE, FINRA, Coinbase, and Ken French data.

The Python interface includes functions such as prices, panel, fundamentals, restatements, factors, macro, claim, claims, crypto, short_volume, and sentiment. These functions are synchronous and return pandas data, including the known_at column rather than removing it for presentation.

Limitations and notes

Vintage focuses on research data and backtest validation, not execution realism. Its documented implemented safeguards include point-in-time panels, mandatory turnover costs, deflated Sharpe calculations, and a session trial ledger. Probability of Backtest Overfitting, purged cross-validation, minimum backtest length, Newey–West adjustment, and square-root market impact are listed as planned rather than implemented features.

The project warns that a universe containing names that exist today can introduce survivorship bias. It also distinguishes restatements, government revisions, membership changes, reporting lags, and price adjustments because current data may differ from what was available at the time.