stockdata-mcp

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

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:

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

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:

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.