marketlens-mcp

A read-only Model Context Protocol server for market data and analytics. It answers in one vendor-neutral schema whatever the data provider (Alpaca is built in; other providers plug in), keeps large results out of the model’s context window in a local DuckDB result store that the model queries with read-only SQL, computes common analytics (returns, volatility, correlation, drawdown, beta, …) on those stored results, and lets you choose which capabilities it may use. With the optional data extra it also answers from official sources, point in time: FRED, BLS and BEA series (CPI, the unemployment rate, payrolls, GDP), SEC EDGAR filings, XBRL facts, fundamentals, earnings releases, insider trades, 13F and fund holdings, the FOMC, NY Fed reference rates and the Treasury’s yield curve, auctions, debt and cash, material filing events (8-K items and 6-Ks), plus market calendars. Built in, it also searches EDGAR’s full text (filings_search) and reads official headlines (press releases, speeches, testimony, enforcement and data-release notices) from the Federal Reserve Board, SEC, BLS, BEA, CFTC and ECB feeds; the SEC and BLS parts ask for a contact email in the User-Agent, the rest is keyless. It works with any MCP client and your own provider keys.

Where it sits: this package is the public core. It owns the schema, the result store, the analytics and the Alpaca and official-feeds providers, and it knows nothing about any one application. Official data reaches it two ways: the data extra installs marketlens-data (import name omni), the point-in-time collector, beside it; or an application that already runs that collector behind its own API exposes that API as a plugin (the plugin API below), in which case the extra is not installed and the two never overlap.

Status

Alpha (0.2.0, unreleased). The tool names, the canonical schema (1.1.0) and the plugin API (1.0) are versioned; see CHANGELOG.md.

How it works

flowchart TB
  client["MCP clientClaude Desktop, Claude Code, any MCP client"]
  subgraph server["marketlens-mcp process"]
    direction TB
    transport["transport.pystdio, or streamable HTTP on 127.0.0.1 with a bearer token"]
    policy["config.py + policy.pyconfig.yaml, capabilities on/off"]
    registry["registry.py + manifest.pyevery tool: name, capability, route, models"]
    pipeline["pipeline.pyvalidate args, run the handler, canonical rows"]
    offload["offload.pyinline, or stored with a result_id"]
    trust["trust.py_marketlens envelope, provenance, notes"]
    subgraph providers["providers (one plugin API)"]
      alpaca["alpaca/market, reference, news,portfolio, provider.docs"]
      data["data/ (optional extra)macro, filings, fed_treasury,holidays, calendars"]
      official["official/news_official, filings_search"]