Stock Market Tracker

Servidor MCP para análisis financiero avanzado, monitoreo de acciones e inteligencia de mercado en tiempo real para respaldar decisiones de compra/venta

GitHub
1

Documentación

Servidor MCP Financiero

Deploy to Azure   Deploy to Render   Run on Google Cloud   Deploy to Cloudflare

Azure / Render / GCP Cloud Run alojan el backend MCP · Cloudflare despliega el proxy HTTPS opcional

Un servidor personalizado de Protocolo de Contexto de Modelo (MCP) para análisis financiero avanzado, monitoreo de acciones e inteligencia de mercado en tiempo real. Este servidor proporciona un conjunto de herramientas y endpoints de API para gestión de carteras, resúmenes de mercado, alertas de acciones e información financiera contextual, diseñado para una integración perfecta con Claude Desktop y otros clientes compatibles con MCP.

Despliegue en la Nube con un Solo Clic

Usa los botones en la parte superior de esta página o la guía completa en DEPLOY.md para lanzar un endpoint MCP remoto en https://<host>/mcp.

PlataformaDespliegaAutenticación predeterminadaConfiguración OAuth
Azure Container AppsBackend MCP en Python (azuredeploy.json)mcpAuthMode=staticConfigura mcpAuthMode=oauth + ajustes de Entra en el portal — consulta OAuth (Entra ID)
RenderBackend MCP en Python (render.yaml)MCP_AUTH_MODE=staticConfigura MCP_ACCESS_TOKEN (requerido en modo estático), luego agrega variables de entorno OAuth en el panel de Render si es necesario
Google Cloud RunBackend MCP en Python (Dockerfile / GHCR)MCP_AUTH_MODE=staticConfigura variables de entorno OAuth en Cloud Run → Variables y secretos — consulta gcp/README.md
Cloudflare WorkerSolo proxy HTTPS (cloudflare-worker/)WORKER_AUTH_MODE=staticUsa WORKER_AUTH_MODE=passthrough cuando el backend utiliza JWT OAuth
  • Predeterminado local: MCP_TRANSPORT=stdio (Claude Desktop / clientes MCP locales)
  • Predeterminado en la nube: MCP_TRANSPORT=streamable-http
  • Modos de autenticación: MCP_AUTH_MODE=static|oauth|none — el ID de cliente y el secreto de OAuth van en Claude, no en el servidor

Características Principales

  • Kit de Herramientas de Acciones: Herramientas de cotizaciones, descripción general de la empresa e historial de precios para flujos de trabajo de análisis prácticos.
  • Cartera con Valores en Vivo: Mantén un almacén de lista de seguimiento/posiciones y devuelve contexto de valoración a nivel de cartera.
  • Alertas de Precio Configurables: Configura umbrales de above / below por ticker y evalúa eventos de alerta activados.
  • Capa de Noticias + Contexto: Recupera noticias de mercado y resúmenes de contexto opcionales con sentimiento para flujos de trabajo de investigación.
  • HTTP Transmisible Seguro: Validación de portador estático (MCP_ACCESS_TOKEN) o JWT OAuth (MCP_AUTH_MODE=oauth) para despliegues públicos.
  • Listo para la Nube: Docker + despliegues con un solo clic para Azure Container Apps, Render, Google Cloud Run y proxy Cloudflare Worker.

Descripción General del Sistema

Endpoints y Herramientas Principales

  • get_stock_quote(ticker: str)
    • Devuelve datos de cotización en vivo normalizados (precio, cambio, capitalización de mercado, volumen, bolsa, marca de tiempo).
  • get_price_history(ticker: str, period: str, interval: str)
    • Devuelve puntos de historial OHLCV listos para gráficos para backtesting y análisis de tendencias.
  • get_company_overview(ticker: str)
    • Devuelve metadatos del perfil de la empresa y campos clave de valoración cuando estén disponibles.
  • get_portfolio()
    • Devuelve posiciones/lista de seguimiento más enriquecimiento de cotizaciones en vivo y resumen del valor de mercado de la cartera.
  • add_stock(...) / remove_stock(...)
    • Agrega o elimina símbolos en el almacén de cartera persistente.
  • set_stock_alert(ticker, above=None, below=None) / get_portfolio_alerts(ticker=None)
    • Configura y evalúa alertas de umbral de precio a partir de reglas basadas en la cartera.
  • get_stock_news(ticker_or_query, max_results=5) y financial_context(query)
    • Proporciona titulares financieros sin procesar y resúmenes de contexto opcionales listos para LLM.

Alertas Automatizadas

  • Integración con Telegram: Envía alertas y resúmenes formateados a un chat de Telegram configurado.
  • Oportunidades de Trading: Detecta y notifica sobre señales de trading accionables.

Resumen Contextual

  • Resumidor de Noticias: Utiliza backends LLM configurables (ollama, openai o auto) para generar resúmenes detallados con etiquetas de sentimiento.
  • Constructor de Prompts: Construye un prompt consciente del mercado para usar en LLMs o asistentes posteriores.

Estructura de Archivos

config/
  alerts_config.json         # Main alert configuration (sector/ticker/thresholds)
  tech_alerts_config.json    # Tech sector-specific alerts
services/
  alerts.py                  # Core alert logic
  tech_alerts.py             # Tech sector alert logic
  telegram_alerts.py         # Telegram integration
  market_summary.py          # Market data and news
  summarizer.py              # News summarization (LLM)
  fetcher.py                 # Web data fetching
  context_builder.py         # Prompt/context construction
  intent_parser.py           # Financial entity extraction
  portfolio.py               # Portfolio management
server.py                    # MCP server entry point and API definitions
requirements.txt             # Python dependencies

Configuración y Personalización

Configuración de Alertas (config/alerts_config.json)

  • Organiza acciones por sector, con umbrales de precio superiores/inferiores personalizables y descripciones.
  • Estructura de ejemplo:
{
  "Tech Giants": {
    "AAPL": {"above": 200, "below": 180, "description": "Apple Inc."}
  },
  "Financial": {
    "JPM": {"above": 160, "below": 140, "description": "JPMorgan Chase"}
  }
}

Variables de Entorno

Configúralas en un archivo .env o en el entorno de tu sistema:

MCP_TRANSPORT=stdio
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO
MCP_AUTH_MODE=static
# Used when MCP_AUTH_MODE=static
MCP_ACCESS_TOKEN=replace_with_strong_secret_for_http
# Used when MCP_AUTH_MODE=oauth
OAUTH_ISSUER_URL=
# Optional additional issuers (space/comma-separated), e.g. sts.windows.net tenant issuer
# OAUTH_ISSUER_URLS=
# Optional JWKS override (otherwise discovered from issuer metadata)
# OAUTH_JWKS_URL=
OAUTH_AUDIENCE=
OAUTH_REQUIRED_SCOPES=mcp.tools
# Optional metadata scopes advertised to clients (use full Entra scope if needed):
# OAUTH_SCOPES_SUPPORTED=api://<api-app-id>/mcp.tools
MCP_RESOURCE_SERVER_URL=
# Optional: built-in OAuth broker for Claude + Entra resource/scope translation
# OAUTH_BROKER_ENABLED=false
# OAUTH_BROKER_SCOPE=api://<api-app-id>/mcp.tools
# OAUTH_BROKER_CLIENT_ID=
# OAUTH_BROKER_CLIENT_SECRET=
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_USER_ID=your_chat_id
SERPAPI_API_KEY=your_serpapi_key
# Optional (deploy templates support it; quotes currently use yfinance)
# ALPHA_VANTAGE_API_KEY=
SUMMARIZER_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=mistral
OPENAI_API_KEY=
OPENAI_MODEL=gpt-4o-mini
# Optional custom OpenAI-compatible base URL
# OPENAI_BASE_URL=
# Optional: set true only for local streamable-http tests
# ALLOW_UNAUTHENTICATED_HTTP=false
# Optional: send Telegram notifications when alerts trigger
# ENABLE_TELEGRAM_ALERTS=false
# Optional persistent path for portfolio file in cloud
# PORTFOLIO_FILE=/data/user_portfolio.json

Modos de Autenticación HTTP

  • static: valida un único token de portador (MCP_ACCESS_TOKEN). Deja MCP_RESOURCE_SERVER_URL sin configurar para que el servidor no publique metadatos de recursos protegidos OAuth (recomendado para Postman y configuración simple de portador en Claude).
  • oauth: valida tokens de acceso JWT de un proveedor OIDC externo usando OAUTH_ISSUER_URL + OAUTH_AUDIENCE (+ OAUTH_JWKS_URL opcional). El OAUTH_ISSUER_URLS opcional permite emisores adicionales de confianza (por ejemplo, sts.windows.net cuando Entra devuelve reclamaciones de emisor v1). El ID de cliente y el secreto de cliente pertenecen a la aplicación conectora / IdP, no a este servidor.
  • none: solo para pruebas locales con ALLOW_UNAUTHENTICATED_HTTP=true.

Microsoft Entra ID (Azure AD)

Para conectores OAuth de Claude, registra una aplicación API de Entra y una aplicación de cliente separada, despliega el backend con MCP_AUTH_MODE=oauth, luego configura Claude con las credenciales de la aplicación de cliente.

Configuración paso a paso de Entra y Claude: DEPLOY.md — OAuth (Entra ID).

Si Claude sigue fallando con Entra AADSTS9010010 mientras Postman funciona con el mismo token, habilita el broker integrado descrito en DEPLOY.md — Broker OAuth para Claude + Entra.

Instalación y Ejecución desde Claude Desktop

Requisitos Previos

  • Python 3.7+
  • Claude Desktop (o cualquier cliente compatible con MCP)
  • Credenciales del bot de Telegram (para alertas)
  • Conexión a internet (para datos de mercado/noticias)

Guía Paso a Paso

  1. Clona el Repositorio

    git clone <this-repo-url>
cd Finance_MCP_Server

  2. Crea y Activa un Entorno Virtual

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. Instala las Dependencias

    pip install -r requirements.txt

  4. Configura las Variables de Entorno

    • Crea un archivo .env en la raíz del proyecto con tus claves de API y tokens: 
      TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_USER_ID=your_chat_id
SERPAPI_API_KEY=your_serpapi_key
MCP_AUTH_MODE=static
MCP_ACCESS_TOKEN=replace_with_strong_secret_for_http
SUMMARIZER_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=mistral
OPENAI_API_KEY=
OPENAI_MODEL=gpt-4o-mini

  5. Edita las Configuraciones de Alertas

    • Modifica config/alerts_config.json y config/tech_alerts_config.json para configurar tus acciones, sectores y umbrales.

  6. Instala el Servidor MCP con la CLI

    • Usa la CLI de MCP para instalar y registrar el servidor para Claude Desktop: 
      mcp install server.py --name "Financial MCP Server"
    • Esto registrará el servidor como una herramienta MCP personalizada, haciéndola detectable por Claude Desktop y otros clientes MCP.

  7. Ejecuta el Servidor MCP mediante la CLI de MCP

    • Inicia el servidor usando la CLI de MCP: 
      mcp run server.py
    • El servidor se iniciará y escuchará solicitudes MCP a través de stdio.

  8. Conéctate desde Claude Desktop

    • En Claude Desktop, agrega una nueva conexión de servidor MCP personalizada.
    • Configura el ejecutable/comando en mcp run server.py (o selecciona el "Financial MCP Server" registrado de la lista de la CLI de MCP).
    • Claude Desktop se comunicará con el servidor usando el protocolo MCP, habilitando todas las herramientas y endpoints descritos.

Ejemplo: Configuración del Servidor MCP en Claude Desktop

Después de instalar y registrar el Financial MCP Server, puedes agregarlo a tu configuración de Claude Desktop. Aquí hay un fragmento de ejemplo de claude_desktop_config.json:

{
  "mcpServers": {
    "Financial-MCP-Server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "server.py"
      ],
      "env": {
        "SERPAPI_API_KEY": "",
        "TELEGRAM_BOT_TOKEN": "",
        "TELEGRAM_USER_ID": "",
        "OPENAI_API_KEY": ""
      }
    }
  }
}
  • Actualiza la sección env con tus claves de API y tokens reales según sea necesario.
  • Esta configuración asegura que Claude Desktop pueda iniciar y comunicarse con tu Financial MCP Server usando el entorno y los argumentos de línea de comandos correctos.

Uso de tus Herramientas en Claude Desktop

Después de instalar y conectar tu Financial MCP Server personalizado, todas las herramientas disponibles aparecerán automáticamente en el menú de herramientas de Claude Desktop. Puedes habilitar o deshabilitar cada herramienta individualmente, lo que facilita el acceso a funcionalidades como análisis de contexto financiero, resúmenes de mercado, gestión de carteras y alertas de acciones directamente desde la interfaz de Claude.

A continuación se muestra una captura de pantalla que muestra cómo se listarán y alternarán las herramientas de tu servidor MCP en Claude Desktop:

Claude Desktop MCP Tools Example

  • Cada herramienta (por ejemplo, financial_context, market_summary, add_stock, etc.) se puede habilitar o deshabilitar según sea necesario.
  • Esta integración perfecta te permite interactuar con tu servidor de análisis financiero usando lenguaje natural y flujos de trabajo basados en herramientas dentro de Claude Desktop.

Ejemplos de Uso

  • Obtén Cotizaciones en Vivo: Usa get_stock_quote y get_company_overview para verificaciones prácticas de acciones.
  • Sigue tu Cartera: Usa add_stock, remove_stock y get_portfolio para mantener y valorar tu lista de seguimiento.
  • Evalúa Alertas: Usa set_stock_alert y get_portfolio_alerts para señales basadas en umbrales.
  • Análisis Contextual: Usa financial_context para obtener y resumir el contexto de mercado para una consulta.

Solución de Problemas y Registros

  • Todos los registros se escriben en financial_mcp.log en la raíz del proyecto.
  • Para depurar, revisa el archivo de registro y asegúrate de que tus variables de entorno y archivos de configuración sean correctos.
  • Si encuentras problemas con Telegram o la obtención de noticias, verifica tus claves de API y tu conexión a internet.