stockdata-mcp

An MCP server for stock research. Two backends, one tool surface.

FMP (fmp_*)	Raw data — statements, quotes, ratios, estimates, prices, dividends. Documented public API. Always on.
Qualtrim (qualtrim_*)	Only what Qualtrim derives on top of FMP — their DCF, curated KPI charts, AI commentary, dip finder, plus your own portfolios and watchlists. Optional.

The split is deliberate. Qualtrim is an FMP customer: it buys the raw data and adds a layer. So this server goes to FMP directly for anything raw, and spends Qualtrim calls only on what is uniquely Qualtrim's.

52 tools — 30 FMP, 22 Qualtrim.

Before you enable the Qualtrim backend

The FMP half of this server is ordinary: a documented public API, a key you sign up for, use it however you like.

The Qualtrim half is not. Qualtrim publishes no API — those routes were read off their shipped JavaScript, and their Terms of Service prohibit both reverse engineering the platform and using automated means to retrieve data from it without prior written consent.

That consent is not transferable and this repository does not grant it. If you want to run the Qualtrim backend, you need your own paid Qualtrim account and your own written permission from Qualtrim, obtained yourself. Ask them directly at support@qualtrim.com.

Without that, run the server with QUALTRIM_USERNAME/QUALTRIM_PASSWORD unset. The FMP tools work fine on their own and nothing here depends on Qualtrim.

The code is published as a reference for how such a client is structured, not as an invitation to point it at someone else's service. Qualtrim's stated remedy for violations is account termination, and their fees are non-refundable.

Install

cd ~/Projects/stockdata-mcp
uv venv && uv pip install -e .
./scripts/set-credentials.sh          # prompts; password input is hidden

set-credentials.sh writes .env with 0600 permissions. It is gitignored. Get a free FMP key at https://site.financialmodelingprep.com/developer/docs.

Register once, for every session on the machine:

claude mcp add stockdata --scope user -- ~/Projects/stockdata-mcp/.venv/bin/stockdata-mcp

No -e flags — the server reads .env itself, so credentials stay out of ~/.claude.json. Real environment variables still override the file, so an MCP client can pass -e if you'd rather.

Check it from any session with backend_status.

Guidance for the model

The server ships its own usage instructions over the MCP protocol — backend choice, free-tier limits, Qualtrim's quirks, how to report figures. Every MCP client receives these automatically, with no extra setup.

There is also a fuller skill at .claude/skills/stock-research/ covering research workflows in more depth. Claude Code reads it from ~/.claude/skills/ (symlink it there). Claude Desktop manages skills in its own location and will not pick it up from that directory — it relies on the server instructions above, which carry the decision-critical parts.

Caching and budget

Responses are cached in a SQLite store at ~/.cache/stockdata-mcp/cache.db. The store is global, not per client — every server process for this user opens the same file, so Claude Code and Claude Desktop share one cache and one daily total. That is required for correctness, not just efficiency: the FMP quota belongs to the API key, and both apps use the same key.

TTL is chosen per endpoint. Quotes last a minute; profiles a week; reference data a month. Historical bars whose date range ended before today never expire, because a close that already happened cannot change. A range running up to today still has a moving edge and gets 15 minutes.

Three tools manage this:

Tool	Purpose
usage_status	Requests sent today, remaining, reset time, cache stats
estimate_cost	What a set of planned calls will cost upstream, before running
cache_clear	Drop expired entries (safe) or a whole backend

estimate_cost exists because the tool-to-request ratio is not 1:1 and is invisible from the caller's side: fmp_search issues 2 requests, fmp_price_target 3, and fmp_quote one per symbol on a free key. It reports worst-case requests, how many legs are already cached, and the net against today's remaining budget. Verified: its prediction matched actual spend exactly on a mixed five-call plan, and returned 0 for the same plan re-run warm.

Measured across six independent processes requesting the same symbol concurrently: 1 upstream request, 5 cache hits, no lock contention.

Configuration

Variable	Default	Purpose
FMP_API_KEY	—	Required for the fmp_* tools
QUALTRIM_USERNAME / QUALTRIM_PASSWORD	—	Enables the qualtrim_* tools
QUALTRIM_ENABLE_WRITES	false	Allow tools that modify your portfolios/watchlists
QUALTRIM_MIN_INTERVAL	1.0	Minimum seconds between Qualtrim requests
FMP_MIN_INTERVAL	0.1	Minimum seconds between FMP requests
MAX_RESPONSE_CHARS	50000	Trim oversized tool payloads
STOCKDATA_ENV_FILE	./.env	Alternate path to the env file

FMP tools

Search and reference: fmp_search, fmp_profile, fmp_quote, fmp_peers, fmp_reference.

Fundamentals: fmp_income_statement, fmp_balance_sheet, fmp_cash_flow, fmp_key_metrics, fmp_ratios, fmp_financial_growth, fmp_financial_scores, fmp_revenue_segmentation, fmp_enterprise_values.

Analysts and valuation: fmp_analyst_estimates, fmp_price_target, fmp_grades, fmp_dcf.

Events and markets: fmp_dividends, fmp_earnings, fmp_earnings_calendar, fmp_historical_prices, fmp_technical_indicator, fmp_screener, fmp_market_movers, fmp_sector_performance, fmp_insider_trading, fmp_news.

fmp_request(endpoint, params) reaches any of FMP's ~250 stable endpoints — ETF holdings, 13F, senate trades, economic indicators, SEC filings, transcripts — without a dedicated wrapper.

What the free tier actually covers

Verified against a live free key: 22 of 29 tools work.

Paid plan required: fmp_screener, fmp_reference, fmp_news, fmp_insider_trading, fmp_technical_indicator. Each returns a clear error naming the plan as the cause.

Two notes:

• Multi-symbol fmp_quote falls back to per-symbol requests, because the batch route is paid. Capped at 20 symbols to protect the daily quota.
• fmp_technical_indicator being paid is easy to route around — fmp_historical_prices is free, so indicators can be computed from OHLCV locally.

The free tier allows roughly 250 requests/day. Pass limit and from_date/to_date; the default on price history is the entire series.

Qualtrim tools

Per-symbol: qualtrim_overview, qualtrim_profile, qualtrim_quote, qualtrim_dcf, qualtrim_kpi_charts, qualtrim_chart, qualtrim_ai_analysis, qualtrim_analyst_estimates.

Comparison: qualtrim_available_kpis, qualtrim_compare.

Your account: qualtrim_portfolios, qualtrim_portfolio, qualtrim_portfolio_look_through_earnings, qualtrim_portfolio_ai_analysis, qualtrim_portfolio_dividends, qualtrim_watchlists, qualtrim_watchlist, qualtrim_dip_finder, qualtrim_watchlist_valuation_ranges.

Escape hatch: qualtrim_request(path), GET only.

Writes (qualtrim_add_watchlist_stock, qualtrim_add_portfolio_holding) refuse to run unless QUALTRIM_ENABLE_WRITES=true.

How the Qualtrim auth actually works

Their shipped bundle looks like bearer-token auth — authTokens in localStorage, Authorization: Bearer. It isn't. Login returns the user object and sets an Express session cookie (connect.sid); that cookie is what authorises normal requests. The bundle's token path is exercised only by its refresh call.

This client keeps a cookie jar, caches the session at ~/.cache/stockdata-mcp/qualtrim-session.json (0600), and logs in again automatically on a 401.

Known drift

Their deployed backend has already diverged from the bundle the routes were read from:

Route in bundle	Reality
/api/insights/{sym}/overview	404 — use overview-flexible
/api/insights/{sym}/dcf-calculator	Returns only a saved calculator; use dcf-calculator-flexible

Both tools already use the working variants. Expect more of this over time — a 404 from a Qualtrim tool means the route moved, not that the ticker is wrong.

qualtrim_dcf returning empty is not a failure; it means no DCF is saved for that symbol in your account.

Qualtrim and their Terms of Service

Qualtrim publishes no API. These routes were read off their shipped JavaScript. Two consequences:

It can break without notice. See "Known drift" above — it already has.

It is restricted by their terms. Their acceptable-use section prohibits using automated means to systematically retrieve data from the site without prior written consent, and separately prohibits reverse engineering the platform. Their enforcement lever is account termination, and their fees are non-refundable.

Consent is obtainable — the prohibition is conditional on it. Ask Qualtrim directly at support@qualtrim.com, and keep their reply.

Defaults here are conservative: 1 request/sec, 2 concurrent max, browser-matching user agent, GET by default, no bulk enumeration. Keep it to interactive research volumes.

Layout

src/stockdata_mcp/
  server.py     tool definitions for both backends
  fmp.py        FMP stable-API client
  qualtrim.py   Qualtrim cookie-session client
  util.py       throttling, response trimming, .env loading
scripts/
  set-credentials.sh
.claude/skills/stock-research/SKILL.md

Not investment advice

Data for your own research. Neither source guarantees accuracy, and nothing here is a recommendation to buy or sell.