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, plus market calendars. It works with any MCP client and your own provider keys.

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

  MCP client (Claude Desktop, Claude Code, any MCP client)
        |  stdio (default), or streamable HTTP on 127.0.0.1 with a bearer token
        v
 +------------------------------- marketlens-mcp -------------------------------+
 |  server.py / transport.py   FastMCP server; reads config.yaml once at start   |
 |  policy.py                  which capabilities are on; off = tool not listed  |
 |  registry.py, manifest.py   every tool: name, capability, route, I/O models   |
 |  trust.py                   wraps every result in the _marketlens envelope    |
 |  pipeline.py                validate args -> provider handler -> canonical    |
 |                             rows + provenance -> offload.py (inline/stored)   |
 |                                                                               |
 |  providers (registered through the same plugin API as third-party plugins)   |
 |   +- alpaca/ -------------+  +- data/ (optional extra) -+  +- plugins -------+ |
 |   | market, reference,    |  | macro, filings,          |  | entry points in | |
 |   | news, portfolio,      |  | fed_treasury, holidays,  |  | marketlens.     | |
 |   | provider.docs         |  | calendars                |  | plugins         | |
 |   +-----------+-----------+  +-------------+------------+  +--------+--------+ |
 |               |                            |                        |          |
 |  results/  DuckDB + Parquet result store (per session, 24 h, capped) <- large |
 |            answers; results_* tools run one guarded read-only SELECT on them |
 |  analytics/  returns, volatility, correlation, resample, align, drawdown,    |
 |              beta: computed in DuckDB on result handles                      |
 +---------------|----------------------------|------------------------|---------+
                 v                            v                        v
     Alpaca market-data API,      marketlens-data (import `omni`):   whatever the
     trading API (reads only),    each publisher's own API -> a      plugin reads
     docs MCP (opt-in)            local point-in-time DuckDB +
                                  Parquet store (FRED, BLS, BEA,
                                  SEC EDGAR, Fed, Treasury, ...)

A tool call, end to end:

1. The client calls a tool. pipeline.py validates the arguments against the tool’s input model (pydantic); a bad argument comes back as invalid_arguments with a hint, before anything is fetched.
2. The provider’s handler calls upstream (paginating up to the fetch ceilings in fetch.py, under the per-provider rate limit in ratelimit.py) and maps the response onto the canonical models in marketlens_schema: SEC-style tickers, UTC instants, decimal-string money, a unit on every number, and a reason on every null.
3. offload.py turns the rows into Arrow. At most inline_max_rows rows and about inline_max_tokens tokens come back inline; anything larger is written to the result store and the model gets a result_id marker instead (typed columns, a preview, ready-made queries; see Large results).
4. trust.py wraps the answer in the _marketlens envelope (provenance, notes, the untrusted-data notice), and the client receives it.

Package layout:

Data sources

What each source needs and how each tool reads it is in Capabilities and defaults, Keys and the tool table. To add a source, see Adding a data source.

Install

uvx marketlens-mcp            # run without installing (recommended for MCP clients)
pipx install marketlens-mcp   # or a user-wide install
pip install marketlens-mcp    # or into an environment you manage

Python 3.11 or newer. Linux and macOS are tested; Windows is not yet supported in this release. The bare command serves MCP over stdio.

With the official-data tools (the data extra, Python 3.13 or newer; see Official data):

uvx --from "marketlens-mcp[data]" marketlens-mcp
pipx install "marketlens-mcp[data]"
pip install "marketlens-mcp[data]"

Dependencies

Outside Python you need:

• An Alpaca account (paper is fine) for the market, reference, news and portfolio tools. Your market-data plan decides the feeds: stock_feed: iex on the free plan, sip with a paid one, delayed_sip for the consolidated tape 15 minutes late; options_feed: indicative unless you have OPRA. Set them in the config so every answer states the feed and delay it really has.
• The official sources’ free keys for the data extra’s tools that need one (see Keys); the rest are keyless.
• Nothing else: no database server, no daemon. The result store and the data store are local folders.

Add it to a client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "marketlens": {
      "command": "uvx",
      "args": ["marketlens-mcp"],
      "env": {
        "ALPACA_API_KEY": "your key id",
        "ALPACA_SECRET_KEY": "your secret key"
      }
    }
  }
}

With the data extra, run it from the extra and add the official sources’ keys (each one only for the tools that need it; see the keys):

{
  "mcpServers": {
    "marketlens": {
      "command": "uvx",
      "args": ["--from", "marketlens-mcp[data]", "marketlens-mcp"],
      "env": {
        "ALPACA_API_KEY": "your key id",
        "ALPACA_SECRET_KEY": "your secret key",
        "FRED_API_KEY": "your FRED key",
        "BEA_API_KEY": "your BEA key",
        "BLS_API_KEY": "your BLS key (optional)",
        "SEC_CONTACT_EMAIL": "[email protected]"
      }
    }
  }
}

SEC_CONTACT_EMAIL is optional but strongly recommended: SEC EDGAR’s fair-access rule asks every client to name a contact. Without it marketlens-data sends a placeholder contact and logs a warning, every sec_ answer carries a note saying so, and SEC may throttle or block such requests. marketlens-mcp doctor says whether it is set, never its value.

Claude Code:

claude mcp add marketlens -e ALPACA_API_KEY=... -e ALPACA_SECRET_KEY=... -- uvx marketlens-mcp

Any other client: run marketlens-mcp (stdio), or marketlens-mcp serve --transport http for streamable HTTP on http://127.0.0.1:8765/mcp with a bearer token (see Security and privacy).

Without Alpaca keys the server still starts and lists its tools; Alpaca tools then answer with a readable error.

Capabilities and defaults

Each tool belongs to one capability. Turn capabilities on or off in the config file; a tool whose capability is off is not listed at all.

The last five are declared whether or not the data extra is installed (a config file naming them is always valid); their tools are listed only where it is. Plugins may declare more capabilities; see Plugins and providers.

Read-only. marketlens-mcp has no tool that places, replaces or cancels orders, closes positions, exercises options, changes account settings, or edits broker watchlists. Those tools do not exist in the package, so no configuration can enable them.

Configuration

Settings live in a YAML file:

• $MARKETLENS_CONFIG if set (the file must exist), else
• $XDG_CONFIG_HOME/marketlens/config.yaml if XDG_CONFIG_HOME is set, else
• ~/.config/marketlens/config.yaml (on every platform).

No file means every default. marketlens-mcp config init writes the commented default file, config path prints where it is, config show prints the effective settings. The server reads the file once at start: restart it after editing. Unknown settings, wrong types and out-of-range values refuse to start with a one-line reason.

Secrets never go in the file. They come from the environment only: ALPACA_API_KEY, ALPACA_SECRET_KEY, MARKETLENS_HTTP_TOKEN for HTTP, and the data sources’ keys (FRED_API_KEY, BEA_API_KEY, BLS_API_KEY, SEC_CONTACT_EMAIL; see the keys). MARKETLENS_LOG_LEVEL (default WARNING) sets the log level; logs go to stderr.

The default file:

version: 1
capabilities:
  market: true
  reference: true
  news: true
  analytics: true
  macro: true             # FRED, BLS, BEA (needs the data extra)
  filings: true           # SEC EDGAR (needs the data extra)
  fed_treasury: true      # FOMC, NY Fed rates, Treasury curve and auctions (needs the data extra)
  holidays: true          # NYSE, SIFMA, OPM market holidays (needs the data extra)
  calendars: false        # Nasdaq calendars: an unofficial endpoint (needs the data extra)
  portfolio: false
  results.export: false
  provider.docs: false
portfolio:
  environment: paper      # paper | live
providers:
  alpaca:
    stock_feed: iex       # iex | sip | delayed_sip | boats | overnight (your plan decides)
    options_feed: indicative   # indicative | opra
    crypto_location: us   # us | us-1 | us-2 | eu-1 | bs-1
    rate_limit_per_minute: 190
    trading_url: null
    data_url: null
  data:
    mode: auto            # auto (fetch and keep) | local (read only what is stored)
    data_dir: null        # absolute folder for the data store; default: the per-user data folder
    ttl_hours: 12         # how long a fetched slice is reused before it is fetched again
    calendar_ttl_minutes: 60
    call_timeout_seconds: 120
results:
  inline_max_rows: 200
  inline_max_tokens: 6000
  query_max_rows: 200
  query_max_bytes: 24000
  query_timeout_seconds: 10
  query_memory_limit: 1GB
  ttl_hours: 24
  max_store_gb: 5
  export_dir: null        # required for results.export
fetch:
  max_rows: 50000
  max_pages: 20
plugins:
  enabled: []
  settings: {}
http:
  port: 8765

Large results

A result of at most 200 rows and about 6,000 tokens comes back inline. Anything bigger is written to the local result store and the tool returns a marker instead: a result_id (such as r_8c1f0a9d3e), the row count, typed columns with units, nulls and min/max, a preview of the first and last rows with the time span, the provenance, the pagination state and three ready-made queries.

The model then works on the handle:

-- results_query: one read-only SELECT; result ids are table names
SELECT ticker, time_bucket(INTERVAL '1 day', t) AS day, last(close ORDER BY t) AS close
FROM r_8c1f0a9d3e GROUP BY ALL ORDER BY day

-- joins of results, window functions and ASOF JOIN work too
SELECT a.t, a.close, b.close AS benchmark
FROM r_8c1f0a9d3e a ASOF JOIN r_51b0c2d4e6 b ON a.t >= b.t

results_query accepts exactly one SELECT or WITH ... SELECT statement. It refuses writes, PRAGMA, SET, ATTACH, COPY, INSTALL, LOAD, file-reading functions and any table that is not a result of the same session; it runs in a fresh in-memory DuckDB that loaded only the referenced results and then disabled file access and locked its configuration. It refuses PIVOT and UNPIVOT (pivot with one max(x) FILTER (WHERE ...) per column instead) and reads at most 8 results in one query. It returns at most max_rows rows (default 50, at most 200; a larger max_rows or LIMIT is lowered, with a note), stops after 10 seconds, and stores its own answer as a new result when it is larger than 24,000 bytes of JSON (results.query_max_bytes) or about 6,000 tokens (or when you pass store=true). Whole-number sums come back as numbers; exact decimals come back as strings, to keep every digit.

Upstream fetches stop at 50,000 rows or 20 pages and say so, with the token to continue when the source gives one (otherwise the note asks for a narrower request). Results live 24 hours in a per-session folder of your cache directory ($MARKETLENS_CACHE_DIR, else ~/Library/Caches/marketlens, %LOCALAPPDATA%\marketlens\Cache or ~/.cache/marketlens), capped at 5 GB with oldest-first eviction. No tool ever shows a filesystem path. marketlens-mcp results list shows the store’s size; results purge --yes empties it.

Analytics

The analytics_* tools take result handles and compute in DuckDB: simple and log returns (optionally by period), rolling annualised volatility (window stated), a correlation matrix, OHLCV resampling (aggregation rules stated), an as-of alignment of two results, drawdown (maximum and series), and beta against a benchmark result. Inputs are validated against the result’s typed columns; large outputs are stored like any other result, and any output with store=true.

Official data (the data extra)

pip install "marketlens-mcp[data]" (Python 3.13 or newer) adds a built-in provider over marketlens-data (import name omni), which fetches each publisher’s own data and keeps it, point in time, in a local DuckDB + Parquet store. 25 tools under five capabilities:

• macro: FRED/ALFRED series with every vintage (macro_series), BLS series (macro_bls_series), BEA NIPA tables (macro_bea_table; BEA states each value’s multiplier separately and marketlens-data does not store it, so a value whose units is Level is not in ones: NIPA dollar levels are usually millions of dollars, and the answer says so), BLS release schedules for the CPI and the jobs report (macro_release_schedule), and the FRED series catalogue (macro_series_catalog).
• filings: SEC EDGAR filings (sec_filings), XBRL facts with restatements (sec_xbrl_facts), 23 point-in-time fundamentals computed from them (sec_fundamentals), 8-K Item 2.02 earnings releases (sec_earnings_releases) and the EPS their press releases state (sec_earnings_figures), Form 4 and 144 insider transactions (sec_insider_trades), 13F holdings (sec_13f_holdings), fund N-PORT reports and holdings (sec_fund_nport, sec_fund_holdings).
• fed_treasury: FOMC meetings and statements, NY Fed reference rates (SOFR, EFFR, OBFR, TGCR, BGCR), the Treasury par yield curve, Treasury auctions, debt to the penny and the Treasury General Account.
• holidays: US market holidays and early closes from NYSE, SIFMA and OPM (calendar_us_holidays), keyless.
• calendars (off by default): Nasdaq’s economic calendar, earnings calendar and earnings history.

Keys

Each source names its own key; set the ones you need in the env block of the server (never in the config file). marketlens-mcp doctor prints one line per source: ready, missing (its tools refuse until it is set), optional, keyless, or its capability off.

A tool whose key is missing answers with the variable to set and where to get it; nothing is fetched.

Where the data lives, and the two modes

The store is a folder of your own: providers.data.data_dir if you set it, else OMNI_DATA_DIR, else the per-user data folder (~/Library/Application Support/marketlens-data on macOS, %LOCALAPPDATA%\marketlens-data on Windows, $XDG_DATA_HOME/marketlens-data or ~/.local/share/marketlens-data elsewhere), created owner-only. marketlens never lets marketlens-data read a .env file.

• mode: auto (the default): a slice (one series, one company, one date) older than ttl_hours is fetched from the publisher and stored, then the answer is read from the store. A second question within the TTL makes no request (cached: true in the provenance).
• mode: local: only what is stored is read; nothing is fetched and no key is needed. An empty answer says so.

Point in time and as_of

Every data tool takes as_of: the answer as it was knowable then (a date means 00:00 UTC; give a datetime with a zone for intraday precision). Each tool’s description states its dataset’s rule:

• vintage (FRED/ALFRED, XBRL facts, fundamentals, N-PORT): exact; the values as published at as_of.
• lagged (BLS, BEA, NY Fed, Treasury, FiscalData, FOMC statements, 13F, insider trades): a row is hidden until its release lag or EDGAR acceptance has passed; revisions are tracked from the first fetch on.
• at_event (SEC filings, earnings releases, press-release EPS): exact EDGAR acceptance instants.
• forward_known (release schedules, FOMC meetings, holidays): known from when they were captured.
• snapshot (Nasdaq calendars): the captured state at as_of; history exists only from the first capture.

Calendars: unofficial, and the only free PMI

calendars is off by default because Nasdaq’s calendar endpoint is unofficial and may change or refuse without notice; turn it on with capabilities: {calendars: true}. It is also the one free source of PMI actual and consensus figures (ISM’s PMI has no free official source): calendar_economic with q: "PMI". Holidays are not behind this switch: they come from their publishers and have their own capability, holidays, on by default.

What the model can ask

• “What was CPI in March 2024, as it was first published?” (macro_series with CPIAUCSL and as_of)
• “Plot the unemployment rate since 2015.” (macro_series UNRATE, or macro_bls_series LNS14000000)
• “Where is SOFR today, and the 2s10s spread?” (fed_reference_rates, macro_series T10Y2Y)
• “List Apple’s 10-K filings and the revenue they reported.” (sec_filings with forms: ["10-K"], sec_fundamentals)
• “Which insiders sold this year?” (sec_insider_trades)
• “What did this fund manager hold last quarter?” (sec_13f_holdings)

Tools

Generated from the built-in tool manifest (make readme). marketlens-mcp tools --markdown prints the same table for your installed configuration, plugins included.

Canonical schema

Every response uses the vendor-neutral models in marketlens_schema (pydantic only, so a data pipeline can use them without the server): tickers in SEC style (BRK-B; crypto pairs as BTC/USD), options by compact OCC symbol, instants in UTC ISO-8601, exact money as decimal strings, a unit on every numeric field, percentages as fractions. A missing value is null, never 0, and every null carries a reason (no_data, not_entitled, not_applicable, …). Every response carries a provenance block: provider, route, feed and delay, as-of time, the normalised request, pages fetched, truncation. marketlens-mcp schema --out DIR writes the JSON Schemas; the built-in ones are in schema/.

Security and privacy

• Read-only: no tool writes to your brokerage account or any provider; the only file a tool can write is an export into the folder you configure, and only with results.export on.
• What leaves your machine: the requests tools make to the provider you configured, and whatever the model reads, which goes to your model provider with the conversation. Brokerage reads are off by default for that reason. The data tools call the publishers directly from your machine; the store is local.
• Untrusted text: every result is wrapped in a _marketlens envelope that tells the model to treat it as data; news and documentation text carry a stronger notice.
• No telemetry: marketlens-mcp sends nothing anywhere except the upstream calls tools make. The FastMCP banner and its update check are off.
• HTTP: serve --transport http listens only on 127.0.0.1 or ::1, requires MARKETLENS_HTTP_TOKEN (at least 32 characters) as a bearer token on every request, and checks the Host and Origin headers.
• Local store: results are Parquet files under your cache directory, owner-only permissions, deleted after 24 hours.

See SECURITY.md to report a vulnerability.

Adding a data source

Pick the path by where the data comes from:

Another Alpaca endpoint

1. make sync-alpaca-specs (step 1) to refresh the bundled OpenAPI specs, then classify every new endpoint: mapped, or excluded with a reason. The parity test fails until each one is classified.
2. Scaffold the tool: marketlens-mcp add-capability NAME --capability market --provider alpaca --operation OPID. It writes the tool skeleton, a fixture and a golden test, and refuses to overwrite anything.
3. Fill in the handler: map the response onto an existing marketlens_schema model (add a model only when none fits), state the feed and delay in the provenance, and give every missing value a reason.
4. make test lint, then make readme schema to regenerate the tool table above and schema/; make check must pass.

An official dataset (the data extra)

The data provider never calls a publisher itself: marketlens-data (import name omni) fetches, stamps each row with when it was knowable, and stores it. A new tool therefore starts from a marketlens-data dataset (omni.list_datasets()); if the publisher is not there yet, add it to marketlens-data first (one Source module with its datasets, natural key, point-in-time policy and tests). Then write the tool in providers/data/tools/, describe its point-in-time rule, name its key in ToolSpec.env, record it in parity.py (and the key in sources.py if the source is new, so doctor reports it), and test it against the fake publisher in tests/data/data_harness.py.

Another vendor, or your own data

A Python package adds capabilities, tools and canonical models through the marketlens.plugins entry-point group:

# your package's pyproject.toml
[project.entry-points."marketlens.plugins"]
myvendor = "myvendor_marketlens:PLUGIN"

# ~/.config/marketlens/config.yaml
plugins:
  enabled: [myvendor]
  settings: {myvendor: {region: us}}
capabilities:
  myvendor_data: true      # a capability your plugin declares

Plugins load only when you name them in plugins.enabled; marketlens-mcp plugins lists what was discovered and why one did not load, and a broken plugin is reported and skipped, never stops the server. A provider plugin reuses the canonical models (marketlens.Bar, marketlens.Quote, …), prefixes its tools with its own name, sets provenance.provider, keeps a list of the vendor endpoints it does not map, and never maps an endpoint that writes. Its large results go to the same result store, so results_query and the analytics_* tools work on them unchanged. Installing a plugin is trusting its code: plugins run in the server’s process. The plugin API, testing helpers (marketlens_mcp.testing) and a complete example are in WRITING_A_PLUGIN.md.

Development

make venv install   # .venv with the package and dev tools (uv)
make test           # pytest (no network, no keys)
make install-data   # add the data extra (Python 3.13); MARKETLENS_DATA_SRC=../omni for a checkout
make test-data      # the data provider's tests (skipped without the extra)
make lint           # ruff check + format check
make readme schema  # regenerate the tool table and schema/
make check          # lint + tests + generated-file checks

marketlens-mcp add-capability NAME --capability ID --provider alpaca|local [--operation OPID] scaffolds a new tool with its golden test. See CONTRIBUTING.md.

License

MIT, see LICENSE. The bundled Alpaca OpenAPI specifications and the adapted maintenance routine come from alpacahq/alpaca-mcp-server (MIT); see THIRD_PARTY_NOTICES.