Skip to main content
Glama
stockdata-mcp

stockdata-mcp

by GlacianNex

FMP + Qualtrim MCP Server

M8ven Score

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 (fmp_*)

Statements, quotes, ratios, estimates, prices, dividends, screening

Yes — needs a free or paid API key

Qualtrim (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_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.

Related MCP server: StocksMCP

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/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

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

FMP_QUALTRIM_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/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

/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.

Development

uv sync            # includes the dev group
uv run pytest -q   # 126 tests, no network, no API quota spent

Tests 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_clear is destructive but idempotent, local tools are not open-world).

  • The write guard holds while QUALTRIM_ENABLE_WRITES is 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_cost reads 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         MIT

Data sources

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 tools
backend_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_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

    C2.8/5.0

    Scored across 33 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An 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.
      26
      30 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      AI-powered stock research MCP server with real-time data, CRUD operations, and interactive dashboard for fundamental analysis and comparisons.
      -
    • A
      license
      A
      quality
      D
      maintenance
      A comprehensive MCP server for stock analysis and trading insights, including stock screening, fundamental analysis, insider trading, options analysis, social media research, and news analysis.
      10
      75
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      39
      199 npm
      8
      MIT