FinBrain MCP

Accede a datos financieros alternativos de grado institucional directamente en tus flujos de trabajo con LLM.

GitHub
9
Prueba este MCPPatrocinado

Documentación

FinBrain MCP 

PyPI version CI License

Requiere Python 3.10+

Un servidor Model Context Protocol (MCP) que expone los conjuntos de datos de FinBrain a clientes de IA (Claude Desktop, extensiones MCP de VS Code, etc.) mediante herramientas simples. Respaldado por el SDK oficial finbrain-python (API v2).

Características

Predicciones de precios impulsadas por IA

Accede a los pronósticos de precios de aprendizaje automático de FinBrain con horizontes diarios (10 días) y mensuales (12 meses). Incluye predicciones medias con intervalos de confianza del 95%.

Análisis de noticias y sentimiento

Explora artículos de noticias recientes para cualquier ticker, o realiza un seguimiento de las puntuaciones de sentimiento diarias agregadas a lo largo del tiempo. Examina noticias en todas las acciones rastreadas.

Datos alternativos

  • Métricas de LinkedIn — Recuento de empleados y tendencias de seguidores como indicadores de salud empresarial
  • Calificaciones de App Store — Datos de rendimiento de aplicaciones móviles para empresas orientadas al consumidor
  • Flujo de opciones — Ratios put/call y volumen para medir el posicionamiento en el mercado
  • Menciones en Reddit — Recuentos de menciones de tickers en subreddits, recopilados cada 4 horas
  • Contratos gubernamentales — Adjudicaciones de contratos del gobierno de EE. UU. de USAspending.gov
  • Solicitudes de patentes — Patentes concedidas por la USPTO asignadas a tickers por cesionario corporativo, con clasificación CPC

Actividad institucional y de personas con información privilegiada

  • Operaciones del Congreso de EE. UU. — Transacciones de acciones divulgadas por representantes y senadores de la Cámara, con la fecha de la transacción y la fecha de divulgación pública (para que puedas medir el retraso en la notificación), el beneficiario real de la cuenta operada (miembro, cónyuge, hijo dependiente, conjunto o un código de cuenta), y los montos presentados normalizados a los tramos legales de la Ley STOCK con la presentación original conservada
  • Cabildeo corporativo — Presentaciones de cabildeo con registrante, ingresos, gastos y códigos de asunto
  • Transacciones de personas con información privilegiada — Presentaciones del Formulario 4 de la SEC que muestran compras y ventas de ejecutivos
  • Calificaciones de analistas — Cobertura de Wall Street y cambios en los precios objetivo

Lo que obtienes

  • ⚡️ Servidor MCP local (sin proxy) que utiliza tu propia clave de API de FinBrain

  • 🧰 Herramientas (JSON por defecto, CSV opcional) con paginación

    • health

    • available_markets, available_tickers, available_regions

    • predictions_by_market, predictions_by_ticker

    • news_by_ticker, news_sentiment_by_ticker

    • app_ratings_by_ticker

    • analyst_ratings_by_ticker

    • house_trades_by_ticker, senate_trades_by_ticker

    • corporate_lobbying_by_ticker

    • insider_transactions_by_ticker

    • linkedin_metrics_by_ticker

    • options_put_call

    • reddit_mentions_by_ticker

    • government_contracts_by_ticker

    • patent_filings_by_ticker

    • recent_news, recent_analyst_ratings

    • screener_sentiment, screener_analyst_ratings, screener_news

    • screener_insider_trading, screener_house_trades, screener_senate_trades

    • screener_put_call_ratio, screener_linkedin, screener_app_ratings, screener_reddit_mentions, screener_government_contracts, screener_patent_filings

  • 🧹 Formas consistentes y amigables para modelos (normalizamos las respuestas crudas de la API)

  • 📱 app_ratings_by_ticker devuelve un series combinado — una fila por fecha, que lleva la aplicación más grande de la empresa en cada tienda — además de apps, un resumen de cada aplicación que publica (platform, app_id, app_name, observation_count, latest_score, latest_ratings_count) y app_count. Una empresa puede publicar muchas aplicaciones (Apple tiene 140 en iOS), por lo que responder una pregunta por aplicación desde series describiría una aplicación como si cubriera toda la empresa: lee apps para ver qué existe, luego pasa app_id para obtener las observaciones de esa aplicación. El resumen no lleva observaciones por diseño — el historial de 140 aplicaciones inundaría el contexto. app_id es null en filas anteriores a la clave por aplicación (la plataforma se conoce, la aplicación no), y un app_id desconocido devuelve available_app_ids en lugar de una serie vacía

  • 🏛️ Las filas de insider_transactions_by_ticker, government_contracts_by_ticker, corporate_lobbying_by_ticker y patent_filings_by_ticker llevan cik — la Clave de Índice Central de la SEC de la empresa al momento del registro, una cadena de 10 dígitos rellenada con ceros ("0000320193"; mantenla como texto, los ceros iniciales son parte del identificador), null cuando el registro no tiene resolución de entidad. Úsala para unir filas a conjuntos de datos con clave SEC (presentaciones EDGAR, tenencias 13F) o a un maestro de valores

  • 🔑 Proporciona tu clave de API mediante la variable de entorno FINBRAIN_API_KEY (una variable de entorno de shell o el bloque env de tu cliente MCP)

Instalación

Opción A — Instalación estándar (pip)

# macOS / Linux / Windows
pip install --upgrade finbrain-mcp

Opción B — Instalación de desarrollo (editable)

# from repo root
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
pip install -e ".[dev]"

Mantén pip (producción) y tu venv (desarrollo) separados para evitar confusiones de rutas.

Opción C — Docker

# Build the image
docker build -t finbrain-mcp:latest .

# Run with your API key
docker run --rm -e FINBRAIN_API_KEY="YOUR_KEY" finbrain-mcp:latest

Consulta DOCKER.md para obtener instrucciones detalladas de uso de Docker.

Configura tu clave de API de FinBrain

A) En la configuración de tu cliente MCP (recomendado / más confiable)

Coloca la clave directamente en la entrada del servidor MCP que usa tu cliente (Claude Desktop o una extensión MCP de VS Code). Esto garantiza que el servidor lanzado la vea, incluso si las variables de entorno del sistema no se recogen.

Claude Desktop (instalación con pip)

{
  "mcpServers": {
    "finbrain": {
      "command": "finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

B) Variable de entorno

Esto también funciona, pero ten en cuenta que debes reiniciar el cliente después de configurarla para que el nuevo valor se herede.

# macOS/Linux
export FINBRAIN_API_KEY="YOUR_KEY"

# Windows (PowerShell, current session)
$env:FINBRAIN_API_KEY="YOUR_KEY"

# Windows (persistent for new processes)
setx FINBRAIN_API_KEY "YOUR_KEY"
# then fully quit and reopen your MCP client (e.g., Claude Desktop)

Consejo: Si la ruta de la variable de entorno no parece funcionar (común en Windows si el cliente ya estaba en ejecución), usa el método JSON de configuración env anterior — es más determinista.

Ejecuta el servidor

Nota: Normalmente no necesitas ejecutar el servidor manualmente — tu cliente MCP (Claude/VS Code) lo inicia automáticamente. Usa los comandos a continuación solo para verificaciones manuales o depuración.

  • Si está instalado (pip):

    finbrain-mcp

  • Desde un venv de desarrollo:

    python -m finbrain_mcp.server

Verificación rápida de salud sin un cliente MCP:

python - <<'PY'
import json
from finbrain_mcp.tools.health import health
print(json.dumps(health(), indent=2))
PY

Conecta un cliente de IA

No se necesita inicio manual: Claude Desktop y VS Code lanzarán el servidor MCP por ti según tu configuración. Solo necesitas ejecutar finbrain-mcp tú mismo para verificaciones rápidas o depuración.

Claude Desktop

Edita tu configuración:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Instalación con pip (paquete publicado):

{
  "mcpServers": {
    "finbrain": {
      "command": "finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Consejo para macOS (ruta completa):

Si "command": "finbrain-mcp" no funciona, encuentra la ruta absoluta y úsala en su lugar.

which finbrain-mcp    # macOS/Linux
# (Windows: where finbrain-mcp)

Configuración de Claude con ruta completa (ejemplo de macOS):

{
  "mcpServers": {
    "finbrain": {
      "command": "/full/path/to/finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Venv de desarrollo (ejecuta el módulo explícitamente):

{
  "mcpServers": {
    "finbrain-dev": {
      "command": "C:\\Users\\you\\path\\to\\repo\\.venv\\Scripts\\python.exe",
      "args": ["-m", "finbrain_mcp.server"],
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Docker:

{
  "mcpServers": {
    "finbrain": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "finbrain-mcp:latest"],
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Después de editar, sal y vuelve a abrir Claude.

VS Code (MCP)

  1. Abre la Paleta de Comandos → “MCP: Open User Configuration”.
    Esto abre tu mcp.json (perfil de usuario).

  2. Agrega el servidor bajo la clave servers:

    {
  "servers": {
    "finbrain": {
      "command": "finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

  3. En Copilot Chat, habilita el Modo Agente para usar las herramientas MCP.

¿Qué puedes preguntarle al agente?

No necesitas conocer los nombres de las herramientas — solo pregunta en lenguaje natural. Ejemplos:

  • Predicciones

    • “Obtén las predicciones diarias de FinBrain para AMZN.”
    • “Muestra predicciones mensuales (horizonte de 12 meses) para AMZN.”
    • “Obtén predicciones diarias de todo el mercado para los tickers del S&P 500.”

  • Noticias

    • “Obtén artículos de noticias recientes para AMZN.”
    • “¿Cuál es el sentimiento de noticias para AMZN del 2025-01-01 al 2025-03-31 (límite 50)?”
    • “Muéstrame las últimas noticias de todas las acciones del S&P 500.”

  • Calificaciones de aplicaciones

    • “Obtén calificaciones de App Store para AMZN entre 2025-01-01 y 2025-06-30.”

  • Calificaciones de analistas

    • “Lista las calificaciones de analistas para AMZN en el primer trimestre de 2025.”

  • Operaciones del Congreso

    • “Muestra operaciones recientes de la Cámara que involucren AMZN.”
    • “Muestra operaciones recientes del Senado que involucren META.”
    • “Para las operaciones de la Cámara de NVDA, ¿cuánto tardó cada miembro en divulgar la operación?”
    • “¿Qué operaciones recientes del Senado se realizaron a través de una cuenta de cónyuge o conjunta?”

  • Cabildeo corporativo

    • “Muestra presentaciones de cabildeo corporativo para AAPL.”
    • “¿Qué firmas de cabildeo ha utilizado MSFT en 2024 (del 2024-01-01 al 2024-12-31)?”

  • Transacciones de personas con información privilegiada

    • “¿Transacciones de personas con información privilegiada recientes para AMZN?”

  • Métricas de LinkedIn

    • “Obtén recuentos de empleados y seguidores de LinkedIn para AMZN (últimos 12 meses).”

  • Opciones (put/call)

    • “¿Cuál es el ratio put/call para AMZN en los últimos 60 días?”

  • Menciones en Reddit

    • “Muestra menciones en Reddit para TSLA en la última semana.”
    • “¿Qué subreddits hablan más sobre AAPL?”

  • Contratos gubernamentales

    • “Muestra contratos gubernamentales adjudicados a LMT en 2025.”
    • “¿Qué empresas tienen las mayores adjudicaciones de contratos gubernamentales?”

  • Solicitudes de patentes

    • “Muestra solicitudes de patentes recientes para AAPL.”
    • “¿Qué empresas tienen más patentes concedidas últimamente?”

  • Filtros (entre tickers)

    • “Filtra el sentimiento en las acciones del S&P 500.”
    • “Muestra las últimas calificaciones de analistas en todas las acciones.”
    • “Filtra operaciones de personas con información privilegiada en todos los tickers (límite 50).”
    • “Filtra datos de LinkedIn para acciones de la región EE. UU.”
    • “¿Cuáles son los tickers más mencionados en Reddit ahora mismo?”
    • “¿Qué empresas están presentando más patentes ahora mismo?”

  • Disponibilidad

    • “¿Qué mercados están disponibles?”
    • “Lista los tickers en el universo de predicciones diarias.”
    • “Muestra las regiones disponibles y sus mercados.”

Notas

  • Formato de fecha: YYYY-MM-DD.
  • Los endpoints de series temporales devuelven los N puntos más recientes por defecto — di “límite 200” para obtener más.
  • Horizonte de predicciones: diario (10 días) o mensual (12 meses).
  • Di “como CSV” para recibir CSV en lugar de JSON.
  • No es necesario especificar un mercado — solo usa el símbolo del ticker directamente.

Desarrollo

# setup
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
pip install -e ".[dev]"  # run tests pytest -q

Estructura del proyecto (nivel alto)

finbrain-mcp
├─ README.md
├─ pyproject.toml
├─ LICENSE
├─ .github/
├─ examples/
├─ src/
│  └─ finbrain_mcp/
│     ├─ __init__.py
│     ├─ server.py                # MCP server entrypoint
│     ├─ registry.py              # FastMCP instance
│     ├─ client_adapter.py        # wraps finbrain-python; caches SDK client; calls normalizers
│     ├─ auth.py                  # resolves API key (env var)
│     ├─ utils.py                 # helpers (latest_slice, CSV, DF->records)
│     ├─ normalizers/             # endpoint-specific shapers
│     └─ tools/                   # MCP tool functions (registered & testable)
└─ tests/                         # pytest suite with a fake SDK

Solución de problemas

  • ENOENT (no se puede iniciar el servidor)

    • Ruta incorrecta en la configuración del cliente. Usa la ruta exacta del venv:

      • …\.venv\Scripts\python.exe + ["-m","finbrain_mcp.server"], o

      • …\.venv\Scripts\finbrain-mcp.exe

  • FinBrain API key not configured

    • Coloca FINBRAIN_API_KEY en el bloque env del cliente o

    • setx FINBRAIN_API_KEY "YOUR_KEY" y reinicia completamente el cliente.

  • Mezcla de instalaciones de desarrollo y producción

    • Mantén pip (producción) y venv (desarrollo) separados.

    • En las configuraciones, apunta a uno u otro — no a ambos.

Licencia

MIT (consulta LICENSE).

Agradecimientos

  • Construido sobre Model Context Protocol y FastMCP.

  • Utiliza el SDK oficial finbrain-python.

© 2026 FinBrain Technologies — Construido con ❤️ para la comunidad cuantitativa.