stockdata-mcp
stockdata-mcp
Un servidor MCP para investigación bursátil. Dos backends, una superficie de herramientas.
FMP ( | Datos brutos: estados financieros, cotizaciones, ratios, estimaciones, precios, dividendos. API pública documentada. Siempre activo. |
Qualtrim ( | Solo lo que Qualtrim deriva sobre FMP: su DCF, gráficos de KPI seleccionados, comentarios de IA, buscador de caídas, además de tus propias carteras y listas de seguimiento. Opcional. |
La división es deliberada. Qualtrim es cliente de FMP: compra los datos brutos y añade una capa. Así que este servidor acude directamente a FMP para todo lo que es bruto, y gasta llamadas a Qualtrim solo en lo que es exclusivamente de Qualtrim.
52 herramientas — 30 de FMP, 22 de Qualtrim.
Antes de habilitar el backend de Qualtrim
La mitad FMP de este servidor es ordinaria: una API pública documentada, una clave que obtienes al registrarte, úsala como quieras.
La mitad Qualtrim no lo es. Qualtrim no publica ninguna API — esas rutas se leyeron de su JavaScript distribuido, y sus Términos de Servicio prohíben tanto la ingeniería inversa de la plataforma como el uso de medios automatizados para recuperar datos de ella sin consentimiento previo por escrito.
Ese consentimiento no es transferible y este repositorio no lo otorga. Si quieres ejecutar el backend de Qualtrim, necesitas tu propia cuenta de pago de Qualtrim y tu propio permiso por escrito de Qualtrim, obtenido por ti mismo. Pregúntales directamente en support@qualtrim.com.
Sin eso, ejecuta el servidor con
QUALTRIM_USERNAME/QUALTRIM_PASSWORDsin definir. Las herramientas FMP funcionan bien por sí solas y nada aquí depende de Qualtrim.El código se publica como referencia de cómo se estructura un cliente de este tipo, no como una invitación a apuntarlo al servicio de otra persona. El remedio declarado por Qualtrim para las infracciones es la cancelación de la cuenta, y sus tarifas son no reembolsables.
Instalación
cd ~/Projects/stockdata-mcp
uv venv && uv pip install -e .
./scripts/set-credentials.sh # prompts; password input is hiddenset-credentials.sh escribe .env con permisos 0600. Está en gitignore.
Obtén una clave FMP gratuita en
https://site.financialmodelingprep.com/developer/docs.
Regístrate una vez, para cada sesión en la máquina:
claude mcp add stockdata --scope user -- ~/Projects/stockdata-mcp/.venv/bin/stockdata-mcpSin banderas -e — el servidor lee .env por sí mismo, así que las credenciales permanecen fuera de
~/.claude.json. Las variables de entorno reales siguen anulando el archivo, por lo que un cliente MCP
puede pasar -e si lo prefieres.
Compruébalo desde cualquier sesión con backend_status.
Guía para el modelo
El servidor envía sus propias instrucciones de uso a través del protocolo MCP — elección de backend, límites del plan gratuito, peculiaridades de Qualtrim, cómo informar cifras. Cada cliente MCP las recibe automáticamente, sin configuración adicional.
También hay una habilidad más completa en .claude/skills/stock-research/ que cubre
flujos de trabajo de investigación con más profundidad. Claude Code la lee desde
~/.claude/skills/ (haz un enlace simbólico allí). Claude Desktop gestiona las habilidades en su propia
ubicación y no la recogerá de ese directorio — depende de las instrucciones del servidor
mencionadas arriba, que contienen las partes críticas para la decisión.
Related MCP server: StocksMCP
Caché y presupuesto
Las respuestas se almacenan en caché en un almacén SQLite en ~/.cache/stockdata-mcp/cache.db.
El almacén es global, no por cliente — cada proceso de servidor para este usuario
abre el mismo archivo, por lo que Claude Code y Claude Desktop comparten una caché y un total diario.
Esto es necesario para la corrección, no solo para la eficiencia: la cuota de FMP
pertenece a la clave de API, y ambas aplicaciones usan la misma clave.
El TTL se elige por endpoint. Las cotizaciones duran un minuto; los perfiles una semana; los datos de referencia un mes. Las barras históricas cuyo rango de fechas terminó antes de hoy nunca expiran, porque un cierre que ya ocurrió no puede cambiar. Un rango que llega hasta hoy todavía tiene un borde móvil y recibe 15 minutos.
Tres herramientas gestionan esto:
Herramienta | Propósito |
| Solicitudes enviadas hoy, restantes, hora de reinicio, estadísticas de caché |
| Lo que costará un conjunto de llamadas planificadas aguas arriba, antes de ejecutarlas |
| Eliminar entradas expiradas (seguro) o un backend completo |
estimate_cost existe porque la proporción herramienta-solicitud no es 1:1 y es
invisible desde el lado del llamante: fmp_search emite 2 solicitudes,
fmp_price_target 3, y fmp_quote una por símbolo en una clave gratuita. Informa
las solicitudes en el peor caso, cuántas patas ya están en caché, y el neto contra
el presupuesto restante de hoy. Verificado: su predicción coincidió exactamente con el gasto real
en un plan mixto de cinco llamadas, y devolvió 0 para el mismo plan re-ejecutado en caliente.
Medido en seis procesos independientes solicitando el mismo símbolo concurrentemente: 1 solicitud aguas arriba, 5 aciertos de caché, sin contención de bloqueo.
Configuración
Variable | Default | Propósito |
| — | Requerida para las herramientas |
| — | Habilita las herramientas |
|
| Permitir herramientas que modifiquen tus carteras/listas de seguimiento |
|
| Segundos mínimos entre solicitudes a Qualtrim |
|
| Segundos mínimos entre solicitudes a FMP |
|
| Recortar cargas de herramientas demasiado grandes |
|
| Ruta alternativa al archivo de entorno |
Herramientas FMP
Búsqueda y referencia: fmp_search, fmp_profile, fmp_quote, fmp_peers,
fmp_reference.
Fundamentales: 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.
Analistas y valoración: fmp_analyst_estimates, fmp_price_target,
fmp_grades, fmp_dcf.
Eventos y mercados: 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) alcanza cualquiera de los ~250 endpoints estables de FMP —
tenencias de ETF, 13F, operaciones del Senado, indicadores económicos, presentaciones SEC, transcripciones —
sin un envoltorio dedicado.
Lo que realmente cubre el plan gratuito
Verificado con una clave gratuita en vivo: 22 de 29 herramientas funcionan.
Se requiere plan de pago: fmp_screener, fmp_reference, fmp_news,
fmp_insider_trading, fmp_technical_indicator. Cada una devuelve un error claro
que nombra el plan como causa.
Dos notas:
fmp_quotemulti-símbolo recurre a solicitudes por símbolo, porque la ruta por lotes es de pago. Limitado a 20 símbolos para proteger la cuota diaria.Que
fmp_technical_indicatorsea de pago es fácil de evitar —fmp_historical_priceses gratuito, por lo que los indicadores se pueden calcular a partir de OHLCV localmente.
El plan gratuito permite aproximadamente 250 solicitudes/día. Pasa limit y
from_date/to_date; el valor predeterminado en el historial de precios es la serie completa.
Herramientas Qualtrim
Por símbolo: qualtrim_overview, qualtrim_profile, qualtrim_quote,
qualtrim_dcf, qualtrim_kpi_charts, qualtrim_chart, qualtrim_ai_analysis,
qualtrim_analyst_estimates.
Comparación: qualtrim_available_kpis, qualtrim_compare.
Tu cuenta: 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.
Vía de escape: qualtrim_request(path), solo GET.
Escrituras (qualtrim_add_watchlist_stock, qualtrim_add_portfolio_holding) se niegan
a ejecutarse a menos que QUALTRIM_ENABLE_WRITES=true.
Cómo funciona realmente la autenticación de Qualtrim
Su paquete distribuido parece autenticación de token portador — authTokens en
localStorage, Authorization: Bearer. No lo es. El inicio de sesión devuelve el objeto de usuario
y establece una cookie de sesión Express (connect.sid); esa cookie es lo que
autoriza las solicitudes normales. La ruta de token del paquete se ejercita solo mediante su
llamada de actualización.
Este cliente mantiene un tarro de cookies, almacena en caché la sesión en
~/.cache/stockdata-mcp/qualtrim-session.json (0600), y vuelve a iniciar sesión
automáticamente en un 401.
Deriva conocida
Su backend desplegado ya ha divergido del paquete del que se leyeron las rutas:
Ruta en el paquete | Realidad |
| 404 — usa |
| Devuelve solo un calculador guardado; usa |
Ambas herramientas ya usan las variantes que funcionan. Espera más de esto con el tiempo — un 404 de una herramienta Qualtrim significa que la ruta se movió, no que el ticker es incorrecto.
qualtrim_dcf que devuelve vacío no es un fallo; significa que no hay DCF guardado para
ese símbolo en tu cuenta.
Qualtrim y sus Términos de Servicio
Qualtrim no publica ninguna API. Estas rutas se leyeron de su JavaScript distribuido. Dos consecuencias:
Puede romperse sin aviso. Ver "Deriva conocida" arriba — ya lo ha hecho.
Está restringido por sus términos. Su sección de uso aceptable prohíbe usar medios automatizados para recuperar datos sistemáticamente del sitio sin consentimiento previo por escrito, y por separado prohíbe la ingeniería inversa de la plataforma. Su palanca de aplicación es la cancelación de la cuenta, y sus tarifas son no reembolsables.
El consentimiento es obtenible — la prohibición es condicional a él. Pregunta a Qualtrim directamente en support@qualtrim.com, y conserva su respuesta.
Los valores predeterminados aquí son conservadores: 1 solicitud/seg, máximo 2 concurrentes, agente de usuario que coincide con el navegador, GET por defecto, sin enumeración masiva. Mantén los volúmenes de investigación interactiva.
Diseño
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.mdNo es asesoramiento de inversión
Datos para tu propia investigación. Ninguna de las fuentes garantiza la precisión, y nada aquí es una recomendación de compra o venta.
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.2647 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