stockdata-mcp
This server provides stock research via MCP: market data, fundamentals, estimates, and screening from Financial Modeling Prep, plus optional Qualtrim analytics and portfolio tools.
Search & reference: find tickers by symbol/name, get company profiles, real-time quotes, peers, and reference lists (sectors, industries, index constituents).
Fundamentals: income statements, balance sheets, cash flow, key metrics, ratios, financial growth, Altman/Piotroski scores, revenue segmentation, enterprise values.
Analysts & valuation: analyst estimates, price targets, upgrade/downgrade grades, DCF valuations.
Markets & events: dividends, earnings history/calendar, historical OHLCV prices, technical indicators, stock screening, market movers, sector performance, insider trading, news.
Escape hatch: call any of FMP's ~250 stable endpoints directly via
fmp_request.Optional Qualtrim tools: DCF, KPI charts, AI commentary, analyst estimates, comparisons, portfolios, watchlists, dip finder, and valuation ranges.
Cost & cache management: check usage status, estimate upstream cost of planned calls, clear stale caches, and inspect backend configuration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@stockdata-mcp Pull the latest financials and DCF for AAPL"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FMP + Qualtrim MCP Server
An MCP server for stock research, backed by Financial Modeling Prep for market and fundamentals data, with optional enrichment from Qualtrim.
Backend | Provides | Required? |
Financial Modeling Prep ( | Statements, quotes, ratios, estimates, prices, dividends, screening | Yes — needs a free or paid API key |
Qualtrim ( | Their own DCF, curated KPI charts, AI commentary, dip finder, and your portfolios and watchlists | No — entirely optional |
Qualtrim is optional
The server is fully functional with Financial Modeling Prep alone. If you
set no Qualtrim credentials, the 22 qualtrim_* tools are simply not
registered and the 33 remaining tools work normally. Nothing degrades, and no
feature depends on Qualtrim being present.
Only enable it if you have a paid Qualtrim subscription and your own written permission from Qualtrim to access it programmatically — see Qualtrim and their Terms of Service below. Without both, leave it off.
Note that Qualtrim is itself a Financial Modeling Prep customer: it licenses the same underlying data and adds a layer on top. So every raw financial figure is available from FMP directly, and this server deliberately routes raw data through FMP even when Qualtrim is configured.
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.
55 tools — 29 Financial Modeling Prep, 22 Qualtrim, and 4 local (budget, cache and status). Without Qualtrim credentials you get 33.
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_PASSWORDunset. 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.
Related MCP server: StocksMCP
Install
cd ~/Projects/stockdata-mcp
uv venv && uv pip install -e .
./scripts/set-credentials.sh # prompts; password input is hiddenset-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-mcpNo -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/fmp-qualtrim-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 |
| Requests sent today, remaining, reset time, cache stats |
| What a set of planned calls will cost upstream, before running |
| 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 |
| — | Required for the |
| — | Enables the |
|
| Allow tools that modify your portfolios/watchlists |
|
| Minimum seconds between Qualtrim requests |
|
| Minimum seconds between FMP requests |
|
| Trim oversized tool payloads |
|
| 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_quotefalls back to per-symbol requests, because the batch route is paid. Capped at 20 symbols to protect the daily quota.fmp_technical_indicatorbeing paid is easy to route around —fmp_historical_pricesis 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/fmp-qualtrim-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 |
| 404 — use |
| Returns only a saved calculator; use |
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.
Development
uv sync # includes the dev group
uv run pytest -q # 126 tests, no network, no API quota spentTests run against a mocked transport and a throwaway cache, so the suite exercises every declared tool without spending an upstream request or touching the Qualtrim account. Notable coverage:
Every tool is invoked with realistic arguments; a tool added without a test entry fails the suite.
Every tool declares all four behaviour hints as booleans, and the values are asserted against actual behaviour (writes are not marked read-only,
cache_clearis destructive but idempotent, local tools are not open-world).The write guard holds while
QUALTRIM_ENABLE_WRITESis unset.Cache semantics: closed date ranges never expire, open-ended ones do, repeat calls send nothing, and POSTs are never served from cache.
Registry drift.
estimate_costreads a request plan that lives apart from the handlers, so it can silently fall out of step. Each tool is run for real, then priced — if the plan built a different endpoint or params, the cache keys differ and the test fails. This caught two genuine gaps while being written.
Layout
src/stockdata_mcp/
server.py tool definitions for both backends
fmp.py FMP stable-API client
qualtrim.py Qualtrim cookie-session client
cache.py shared response cache and usage accounting
plans.py per-tool request plans, for cost preflight
util.py throttling, response trimming, .env loading
tests/ pytest suite, fully mocked
scripts/
set-credentials.sh
.claude/skills/stock-research/SKILL.md
LICENSE MITData sources
Financial Modeling Prep — market data, financial statements, estimates and screening. API docs · Pricing
Qualtrim — optional. Derived analysis and personal portfolio tracking, built on FMP data.
Neither project is affiliated with this one.
Not investment advice
Data for your own research. Neither source guarantees accuracy, and nothing here is a recommendation to buy or sell.
Available Tools
33 toolsbackend_statusA
Report which backends are configured and how this server is set up.
Inputs: no named parameters. Returns: result
cache_clearA
Drop cached responses. Use when data looks stale despite its TTL.
"expired" (the default) only removes entries already past their TTL and is always safe. Clearing live entries means paying for those requests again — note that past price bars never expire by design, because they cannot change.
Inputs: backend. Returns: result
estimate_costA
Say what a set of tool calls will cost upstream before running them.
The tool-to-request ratio is not 1:1 — fmp_search issues two requests, fmp_price_target three, and fmp_quote falls back to one per symbol on a free key. Cached legs cost nothing. Use this before a multi-step analysis, or whenever a plan touches many symbols.
Args: calls: Tool calls to price, e.g. [{"tool": "fmp_profile", "args": {"symbol": "AAPL"}}, {"tool": "fmp_quote", "args": {"symbols": "AAPL,MSFT,NVDA"}}]
Returns per-call worst-case requests, how many legs are already cached, and the net spend against today's remaining budget.
Inputs: calls (required). Returns: result
fmp_analyst_estimatesC
Forward analyst estimates for revenue, EPS, EBITDA and net income.
Inputs: symbol (required), limit, period. Returns: result
fmp_balance_sheetD
Balance sheet statements.
Inputs: symbol (required), limit, period. Returns: result
fmp_cash_flowD
Cash flow statements.
Inputs: symbol (required), limit, period. Returns: result
fmp_dcfB
FMP's discounted cash flow valuation for a symbol.
Args: levered: Use the levered (post-debt) DCF instead of the standard one.
Inputs: symbol (required), levered. Returns: result
fmp_dividendsB
Dividend history for a symbol: declaration, record, payment dates and amounts.
Inputs: symbol (required), limit. Returns: result
fmp_earningsB
Earnings history and upcoming dates: actual vs estimated EPS and revenue.
Inputs: symbol (required), limit. Returns: result
fmp_earnings_calendarB
Market-wide earnings calendar over a date range (YYYY-MM-DD).
Inputs: to_date (required), from_date (required). Returns: result
fmp_enterprise_valuesC
Enterprise value, market cap, and net debt over time.
Inputs: symbol (required), limit, period. Returns: result
fmp_financial_growthC
Period-over-period growth rates across the three statements.
Inputs: symbol (required), limit, period. Returns: result
fmp_financial_scoresB
Altman Z-score and Piotroski F-score for a symbol.
Inputs: symbol (required). Returns: result
fmp_gradesC
Analyst upgrades and downgrades, or the consensus grade distribution.
Inputs: symbol (required), historical. Returns: result
fmp_historical_pricesA
Historical OHLCV data.
Args: symbol: Ticker, index (^GSPC), crypto (BTCUSD) or FX pair (EURUSD). from_date: Start date, YYYY-MM-DD. Strongly recommended — without it you get the full history, which is large. to_date: End date, YYYY-MM-DD. interval: "1day" for end-of-day, otherwise an intraday bar size. full: For daily data, include change/VWAP columns rather than the light form.
Inputs: symbol (required), full, to_date, interval, +1 more. Returns: result
fmp_income_statementC
Income statements. Use limit to control how many periods come back.
Inputs: symbol (required), limit, period. Returns: result
fmp_insider_tradingC
Insider transactions for a symbol, or aggregate insider buy/sell statistics.
Inputs: symbol (required), limit, statistics. Returns: result
fmp_key_metricsC
Per-share and valuation metrics: P/E, EV/EBITDA, ROIC, FCF per share, etc.
Args: ttm: Return trailing-twelve-month values instead of discrete periods.
Inputs: symbol (required), ttm, limit, period. Returns: result
fmp_market_moversA
Today's biggest gainers, biggest losers, or most actively traded names.
Inputs: kind. Returns: result
fmp_newsA
Recent news articles for one or more comma-separated symbols.
Inputs: symbols (required), limit. Returns: result
fmp_peersC
Comparable companies for a symbol, as identified by FMP.
Inputs: symbol (required). Returns: result
fmp_price_targetB
Analyst price-target summary and consensus, plus the current rating snapshot.
Inputs: symbol (required). Returns: result
fmp_profileC
Company profile: sector, industry, market cap, description, exchange, CEO.
Inputs: symbol (required). Returns: result
fmp_quoteA
Current quote for one or more symbols.
Args: symbols: One symbol, or several comma-separated ("AAPL,MSFT,NVDA"). short: Return only price/volume rather than the full quote.
Inputs: symbols (required), short. Returns: result
fmp_ratiosC
Financial ratios: margins, liquidity, leverage, returns, payout.
Inputs: symbol (required), ttm, limit, period. Returns: result
fmp_referenceA
Look up the valid values for screener filters, or an index's constituents.
Inputs: kind (required). Returns: result
fmp_requestA
Call any FMP stable endpoint directly — an escape hatch for the ~250 endpoints without a dedicated tool here (ETF holdings, 13F, senate trades, economic indicators, SEC filings, transcripts, and so on).
Args: endpoint: Path after /stable/, e.g. "etf/holdings" or "treasury-rates". params: Query parameters, e.g. {"symbol": "SPY"}. The API key is added automatically.
Inputs: endpoint (required), params. Returns: result
fmp_revenue_segmentationB
Revenue split by product line or by geography.
Inputs: symbol (required), by. Returns: result
fmp_screenerB
Screen for stocks matching fundamental and market filters.
Call fmp_reference("sectors") or fmp_reference("industries") first if you need the exact spelling of a sector or industry value.
Inputs: limit, is_etf, sector, country, +14 more. Returns: result
fmp_searchA
Find a ticker symbol by symbol fragment or company name.
Args: query: A symbol fragment ("AAP") or company name ("Apple"). limit: Max results. exchange: Optional exchange filter, e.g. "NASDAQ".
Inputs: query (required), limit, exchange. Returns: result
fmp_sector_performanceB
Sector performance, or sector P/E ratios, as of a date (YYYY-MM-DD).
Inputs: pe, date. Returns: result
fmp_technical_indicatorD
A technical indicator series — useful for backtesting signal ideas.
Inputs: symbol (required), to_date, from_date, indicator, +2 more. Returns: result
usage_statusA
Upstream requests spent today, what remains, and when the budget resets.
Counts requests that actually left this machine — cache hits are free and
are reported separately as saved. The count is shared by every client on
this machine (Claude Code and Claude Desktop use the same store and the
same API key), so it reflects total spend, not this session's.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Most tools map cleanly to a distinct data category, and the fmp_ prefixes help separate market data, fundamentals, analyst data, and utilities. A few analyst-related tools and the key_metrics/ratios pair overlap enough that an agent must read the descriptions carefully to pick the right one.
All data tools follow a consistent fmp_<category> snake_case pattern, making the group recognizable and predictable. The operational tools like usage_status and cache_clear break the prefix convention, but they are still readable and clearly grouped, so the deviation is minor.
At 33 tools, the server exceeds the 25+ threshold and presents a heavy surface for an agent to navigate. Many fundamental and analyst tools could be consolidated, and fmp_request already provides a catch-all for less common FMP endpoints.
The set covers the core market-data workflow thoroughly: quotes, historical prices, fundamentals, financial statements, dividends, earnings, analyst data, screening, news, and insider trades. The fmp_request escape hatch also covers any remaining FMP endpoints, so there are no obvious dead ends.
Maintenance
Related MCP Connectors
Production MCP server for US equity and options intelligence: real-time IV radar, Monte Carlo simulation, options pressure, strategy backtesting, AI prediction, pre-trade risk analysis, and automated stock research reports.
MCP server for Financial Modeling Prep API with 250+ financial data tools
Hosted MCP server for Indian NSE/BSE stock research: 59 tools for quotes, financials and ratios, peers, shareholding and pledge, filings with extracted facts, screens, F&O and FII/DII context. Source and freshness on every answer; no buy/sell calls.
Research-only MCP server: your AI as a quant research desk. 90 tools, no trades, no brokers.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that provides comprehensive access to real-time stock quotes, financial statements, analyst estimates, and technical indicators via the Financial Modeling Prep API. It enables users to conduct in-depth financial analysis and track market performance through specialized tools, resources, and prompt templates.2630 npm1MIT
- FlicenseNot gradedqualityDmaintenanceAI-powered stock research MCP server with real-time data, CRUD operations, and interactive dashboard for fundamental analysis and comparisons.-
- AlicenseAqualityDmaintenanceA comprehensive MCP server for stock analysis and trading insights, including stock screening, fundamental analysis, insider trading, options analysis, social media research, and news analysis.1075MIT
- AlicenseAqualityBmaintenanceA modular MCP server providing 64 tools across 13 modules for real-time stock and crypto market data, including scanning, technical analysis, options flow, insider trades, and personalized watchlists.39199 npm8MIT