FinBrain MCP

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

Documentación

FinBrain MCP

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

Nombre del paquete: finbrain-mcp
Punto de entrada CLI: finbrain-mcp
Documentación: finbrain.tech/integrations/mcp

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 temas
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)
🏛️ Las filas de insider_transactions_by_ticker, government_contracts_by_ticker, corporate_lobbying_by_ticker y patent_filings_by_ticker llevan cik — la Clave Central de Índice (CIK) de la SEC de la empresa en la fecha 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 con conjuntos de datos clave de la SEC (presentaciones EDGAR, tenencias 13F) o 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 de configuración JSON env anterior: es más determinista.

Ejecutar 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

Conectar 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 (ejecutar 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)

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

Agrega el servidor bajo la clave servers:

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

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

¿Qué puedes preguntarle al agente?

No necesitas saber 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 recientes de personas con información privilegiada 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 durante la última semana.”
- “¿Qué subreddits hablan más de 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 (multi-ticker)
- “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.
Mezclar 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.