Skip to main content
Glama
stockdata-mcp

stockdata-mcp

by GlacianNex

stockdata-mcp

Un servidor MCP para investigación bursátil. Dos backends, una superficie de herramientas.

FMP (fmp_*)

Datos brutos: estados financieros, cotizaciones, ratios, estimaciones, precios, dividendos. API pública documentada. Siempre activo.

Qualtrim (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_PASSWORD sin 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 hidden

set-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-mcp

Sin 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

usage_status

Solicitudes enviadas hoy, restantes, hora de reinicio, estadísticas de caché

estimate_cost

Lo que costará un conjunto de llamadas planificadas aguas arriba, antes de ejecutarlas

cache_clear

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

FMP_API_KEY

—

Requerida para las herramientas fmp_*

QUALTRIM_USERNAME / QUALTRIM_PASSWORD

—

Habilita las herramientas qualtrim_*

QUALTRIM_ENABLE_WRITES

false

Permitir herramientas que modifiquen tus carteras/listas de seguimiento

QUALTRIM_MIN_INTERVAL

1.0

Segundos mínimos entre solicitudes a Qualtrim

FMP_MIN_INTERVAL

0.1

Segundos mínimos entre solicitudes a FMP

MAX_RESPONSE_CHARS

50000

Recortar cargas de herramientas demasiado grandes

STOCKDATA_ENV_FILE

./.env

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_quote multi-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_indicator sea de pago es fácil de evitar — fmp_historical_prices es 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

/api/insights/{sym}/overview

404 — usa overview-flexible

/api/insights/{sym}/dcf-calculator

Devuelve solo un calculador guardado; usa dcf-calculator-flexible

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

No 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 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
    ResponsivenessOutdated data

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