stock-scanner

stock-scanner-mcp

Un servidor MCP modular para Claude Code y Claude Desktop que proporciona acceso en tiempo real a datos de mercado de acciones y criptomonedas. Escanea mercados, revisa indicadores técnicos, monitorea operaciones de información privilegiada, rastrea resultados trimestrales, analiza el flujo de opciones y, opcionalmente, guarda tus propias listas de seguimiento y notas de tesis desde un solo servidor.

69 herramientas en 15 módulos — 11 módulos funcionan sin claves API, incluido un Market Workspace opcional con estado.

Inicio Rápido

Tres pasos para obtener la experiencia completa: configuración del servidor, habilidades de trading y configuración del workspace.

Paso 1 — Añade el servidor a tu configuración de MCP

Copia este bloque de configuración completo en tu archivo de configuración:

• Claude Code: ~/.claude.json (global) o .mcp.json (específico del proyecto)
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "stock-scanner": {
      "command": "npx",
      "args": ["-y", "stock-scanner-mcp", "--enable-workspace"],
      "env": {
        "FINNHUB_API_KEY": "your-key-here",
        "ALPHA_VANTAGE_API_KEY": "your-key-here",
        "FRED_API_KEY": "your-key-here"
      }
    }
  }
}

Esto te da 49 herramientas de inmediato sin claves API. Las claves API son opcionales y gratuitas: desbloquean 20 herramientas adicionales para cotizaciones en tiempo real, noticias, resultados trimestrales y datos económicos. Consulta API Keys a continuación para saber dónde obtenerlas.

Configuración mínima — si no quieres workspace ni claves API, usa esto en su lugar:

{
  "mcpServers": {
    "stock-scanner": {
      "command": "npx",
      "args": ["-y", "stock-scanner-mcp"]
    }
  }
}

Esto te da 42 herramientas sin estado sin almacenamiento local de datos.

Reinicia Claude Desktop después de guardar. Claude Code detecta la configuración automáticamente.

Atajo para Claude Code — instala como plugin en lugar de los Pasos 1 y 2. Si usas Claude Code, omite la configuración manual anterior e instala todo con dos comandos:

/plugin marketplace add yyordanov-tradu/stock-scanner-mcp
/plugin install stock-scanner@tradu-marketplace

Ejecuta /reload-plugins, luego /mcp — deberías ver el servidor stock-scanner listado como conectado. El primer lanzamiento ejecuta npx -y stock-scanner-mcp, que descarga el paquete una vez (luego queda en caché). El plugin habilita el workspace por defecto (los datos se almacenan en ~/.stock-scanner-mcp) y pasa las claves API opcionales (FINNHUB_API_KEY, ALPHA_VANTAGE_API_KEY, FRED_API_KEY) desde tu entorno; los módulos sin clave se omiten automáticamente.

El plugin ya incluye las habilidades — NO ejecutes el Paso 2. Las 19 habilidades se incluyen con el plugin y se cargan bajo el espacio de nombres stock-scanner:, p. ej. /stock-scanner:analyze-stock AAPL, /stock-scanner:morning-briefing, /stock-scanner:setup-market-workspace. Ejecutar también el instalador del Paso 2 copia un segundo conjunto sin prefijo en ~/.claude/skills/, y ambos entran en conflicto — el Paso 2 es solo para la instalación manual (sin plugin). Después de instalar, ve directamente al Paso 3, usando el comando con espacio de nombres: /stock-scanner:setup-market-workspace.

Paso 2 — Instala las habilidades de trading

Omite este paso si instalaste mediante el plugin anterior — el plugin ya incluye estas habilidades (como stock-scanner:<name>). Este paso es solo para la configuración manual del Paso 1.

Ejecuta este comando en tu terminal:

npx -p stock-scanner-mcp stock-scanner-install-skills

Esto instala 19 comandos de barra (como /morning-briefing, /analyze-stock AAPL, /setup-market-workspace) en ~/.claude/skills/ para que estén disponibles en cada sesión de Claude Code. Consulta Trading Skills para ver la lista completa.

Paso 3 — Configura tu workspace

Ejecuta /setup-market-workspace en Claude Code. Hace tres preguntas rápidas:

> /setup-market-workspace

Setting up your market workspace — I'll ask a few quick questions to get started...

1. What kind of trader or investor are you?
   (e.g., options trader, swing trader, long-term investor, crypto-focused)

   → "I'm mostly a swing trader, also watch crypto"

2. Which names or assets should I save to your core watchlist?
   (e.g., AAPL, MARA, BTC, Gold)

   → "MARA, HOOD, SOFI, BTC, ETH"

3. Do you want a daily or weekly market review?

   → "Daily"

Una vez respondidas, guarda tu perfil y crea una lista de seguimiento core:

✓ Workspace saved

  Profile     swing trader | daily review
  Watchlist   core — MARA, HOOD, SOFI, BTC, ETH

También puedes omitir la habilidad y pedirle a Claude directamente: "Configura mi workspace — soy un trader de swing, crea una lista de seguimiento principal con MARA, HOOD, BTC, revisiones diarias."

Eso es todo. Ahora tienes 69 herramientas, 19 habilidades y un workspace personalizado. Prueba /workspace-morning-brief para tu primer escaneo de mercado personalizado.

Lo Que Puedes Hacer

"What are the top gaining stocks today?"
"Show me technicals for AAPL on the hourly timeframe"
"Any insider trades for TSLA in the last 30 days?"
"What's the options chain for AAPL expiring next Friday?"
"What's the current fed funds rate and CPI trend?"
"Convert $10,000 USD to EUR"
"Set up a core watchlist with MARA, HOOD, and BTC"
"Give me a personalized morning brief for my saved watchlist"

Destacados

• Escaneo de acciones — filtra por precio, RSI, volumen, capitalización de mercado con filtros personalizados
• Análisis técnico — RSI, MACD, Bandas de Bollinger, medias móviles, pivotes en múltiples marcos temporales
• Flujo de opciones — cadenas con griegas, detección de actividad inusual, max pain, movimiento implícito
• Operaciones de información privilegiada — transacciones del Formulario 4 procesadas con detalles de compra/venta/otorgamiento
• Resultados trimestrales y noticias — calendario, calificaciones de analistas, noticias de empresas, interés corto
• Criptomonedas — cotizaciones en tiempo real, indicadores técnicos, monedas en tendencia, estadísticas del mercado
• Macro — IPC, PIB, tasa de fondos federales, calendario económico, datos de la curva de rendimiento
• Forex — 31 pares de divisas del BCE, conversión, tasas históricas
• Sentimiento — Índice de Miedo y Codicia de CNN, Miedo y Codicia de Cripto
• Market Workspace — guarda un perfil de trading, listas de seguimiento con nombre y notas de tesis para flujos de trabajo personalizados entre sesiones

Habilidades de Trading

19 flujos de trabajo listos para usar que encadenan múltiples herramientas en un análisis estructurado. Cada habilidad orquesta de 5 a 14 herramientas en paralelo y produce un veredicto con dirección, confianza y niveles clave.

Las habilidades se degradan con elegancia cuando faltan claves API opcionales. Las habilidades del workspace requieren --enable-workspace en la configuración del servidor.

npx -p stock-scanner-mcp stock-scanner-install-skills                    # all 19 skills
npx -p stock-scanner-mcp stock-scanner-install-skills --scope project    # project only (.claude/skills/)
npx -p stock-scanner-mcp stock-scanner-install-skills --category macro   # one category
npx -p stock-scanner-mcp stock-scanner-install-skills --category workspace # workspace skills only
npx -p stock-scanner-mcp stock-scanner-install-skills --list             # list without installing
npx -p stock-scanner-mcp stock-scanner-install-skills --force            # overwrite existing

Consulta skills/README.md para ver el catálogo completo.

Market Workspace

El Market Workspace es una capa opcional con estado que recuerda tu contexto de trading entre sesiones: tu estilo de trading, listas de seguimiento con nombre y notas de tesis de inversión por símbolo. Habilidades como /workspace-morning-brief usan este contexto para ofrecer escaneos de mercado personalizados en lugar de genéricos.

Lo que puedes hacer con él

• /workspace-morning-brief — escaneo pre-mercado personalizado que lee tu perfil y lista de seguimiento, verifica resultados trimestrales, noticias y acción del precio de tus nombres, y resalta lo que importa hoy
• Añadir más listas de seguimiento — pídele a Claude: "Crea una lista de seguimiento llamada 'earnings' con AAPL, MSFT, GOOG"
• Rastrear tesis de inversión — guarda tu razonamiento por ticker para que el sistema lo monitoree por ti (ver abajo)
• Actualizar en cualquier momento — "Añade NVDA a mi lista de seguimiento principal" o "Cambia mi cadencia de revisión a semanal"

Seguimiento de Tesis

Guarda tu razonamiento de inversión por ticker — dirección, niveles clave, catalizadores y marco temporal — para que el sistema pueda monitorearlo entre sesiones.

Guarda una tesis:

"My thesis on NIO: bullish above $6.35, that confirms the uptrend. Below it the setup is invalid."

Claude guarda la tesis estructurada:

Cómo funciona en la práctica: Cuando ejecutas /workspace-morning-brief, el informe cruza tus tesis guardadas con la acción del precio en vivo:

• NIO cae a $6.10 → "NIO rompió por debajo de tu piso de tesis de $6.35 — reevalúa."
• NIO sube a $7.20 → "NIO se mantiene por encima de tu nivel de $6.35 — la tesis alcista sigue intacta."

Sin una tesis, el informe solo reporta un cambio de precio. Con una tesis, te dice si el movimiento importa para tu plan.

Cada tesis admite cinco campos: summary, bullCase, bearCase, catalyst y timeframe. Puedes guardar hasta 200 tesis por workspace.

Referencia de configuración

Los datos se almacenan localmente en workspace.json — sin sincronización en la nube, sin llamadas externas. Si omites --enable-workspace, el servidor permanece completamente sin estado y no escribe datos locales.

Para la lista completa de herramientas del workspace, consulta la referencia de herramientas a continuación.

Documentación

• Instalación y Configuración — Cómo poner en marcha el servidor MCP en Claude Code o Cursor
• Habilidades de Trading — Flujos de trabajo listos para análisis profesional
• API HTTP Sidecar — Endpoints REST para clientes que no usan MCP
• Despliegue con Docker — Ejecución en contenedores con persistencia del workspace
• Preguntas Frecuentes y Solución de Problemas — Problemas comunes y soluciones

Módulos

Los módulos se habilitan automáticamente cuando se configura su clave API. Los módulos sin clave están siempre habilitados, excepto workspace, que requiere --enable-workspace.

Para una lista completa de cada herramienta con descripciones, consulta la Referencia Completa de Herramientas a continuación.

Referencia Completa de Herramientas (69 herramientas)

TradingView — Escaneo de Acciones (sin clave API)

TradingView — Cripto (sin clave API)

SEC EDGAR — Presentaciones y Propiedad (sin clave API)

CoinGecko — Inteligencia de Criptomonedas (sin clave API)

Opciones — Cadenas, Griegos y Actividad Inusual (sin clave API)

Opciones CBOE — Sentimiento Put/Call (sin clave API)

Sentimiento — Miedo y Codicia (sin clave API)

Frankfurter — Tipos de Cambio Forex (sin clave API)

Reddit — Tickers en Tendencia y Sentimiento (sin clave API)

Amplitud de Mercado — Indicadores de Amplitud (sin clave API)

Mercado Unificado — Enrutamiento Inteligente (sin clave API)

Espacio de Trabajo — Contexto Personalizado (opcional, sin clave API)

Habilitado solo cuando inicias el servidor con --enable-workspace.

Finnhub — Noticias, Ganancias y Macro (requiere FINNHUB_API_KEY)

Alpha Vantage — Fundamentos e Historia (requiere ALPHA_VANTAGE_API_KEY)

FRED — Datos Económicos de EE. UU. (requiere FRED_API_KEY)

Configuración

Opciones de CLI

npx -y stock-scanner-mcp --modules tradingview,sec-edgar    # Enable specific modules only
npx -y stock-scanner-mcp --default-exchange NYSE             # Set default exchange
npx -y stock-scanner-mcp --enable-workspace                  # Turn on local workspace tools
npx -y stock-scanner-mcp --enable-workspace --data-dir /tmp/market-workspace  # Custom data directory
npx -y stock-scanner-mcp --help                              # Show all options

Claves API (opcional)

Las tres claves son gratuitas — no se requiere tarjeta de crédito:

Agrégalas al bloque env en tu configuración de MCP (ver Inicio rápido).

Uso con otros clientes MCP

Cualquier cliente MCP que admita servidores stdio puede ejecutar este paquete. Usa la misma configuración JSON de Inicio rápido. Si tu cliente no expone npx, instala el paquete primero y apunta el cliente al binario instalado en su lugar.

Sidecar HTTP

Un servidor HTTP opcional que expone todas las herramientas como endpoints REST para integraciones no MCP (GPT Actions, interfaces de chat, pipelines de LLM). Incluye una especificación OpenAPI 3.1 para el descubrimiento automatizado de herramientas.

npx stock-scanner-sidecar              # Start on port 3200
npx stock-scanner-sidecar --port 8080  # Custom port

# Optional: Enable the stateful Market Workspace via HTTP
npx stock-scanner-sidecar --enable-workspace --data-dir ./my-data

# Access the OpenAPI spec
curl http://localhost:3200/openapi.json

Consulta API HTTP Sidecar para detalles de endpoints.

69 herramientas expuestas como rutas REST, incluyendo /market/quote, /options/chain, /workspace/profile, y más.

Límites de Tasa

Todos los módulos usan caché TTL en memoria para minimizar las llamadas a la API.

Desarrollo

npm install && npm run build && npm test
npm run lint               # TypeScript type checking
npm run validate-tools     # Tool description quality check
npm run validate-doc-tools # Skill/command tool reference check

Artefactos de Credibilidad

• Ejemplos de referencia
• Transcripciones de muestra
• Instantánea de latencia y fiabilidad

src/
├── index.ts              # MCP server entry + prompt definitions
├── config.ts             # CLI arg parsing
├── registry.ts           # Module auto-discovery and filtering
├── modules/
│   ├── tradingview/      # 10 tools — stock scanning, quotes, technicals, sectors, indices
│   ├── tradingview-crypto/ # 4 tools — crypto scanning and technicals
│   ├── sec-edgar/        # 6 tools — filings, insider trades, holdings
│   ├── coingecko/        # 3 tools — crypto market data
│   ├── options/          # 5 tools — options chains, Greeks, unusual activity, implied move
│   ├── options-cboe/     # 1 tool  — CBOE put/call ratio sentiment
│   ├── workspace/        # 7 tools — stateful profile, watchlists, thesis notes
│   ├── finnhub/          # 9 tools — quotes, news, earnings, analyst ratings, short interest
│   ├── alpha-vantage/    # 5 tools — quotes, fundamentals, dividends
│   ├── fred/             # 4 tools — economic calendar, indicators, historical data
│   ├── sentiment/        # 2 tools — Fear & Greed indexes (market + crypto)
│   ├── frankfurter/      # 5 tools — forex exchange rates (ECB, 31 currencies)
│   ├── reddit/           # 4 tools — trending tickers, mentions, sentiment, watchlist scan from Reddit
│   └── unified-market/   # 3 tools — smart provider routing for quotes/profiles/technicals
├── sidecar/
│   ├── index.ts          # HTTP sidecar entry point (port 3200)
│   ├── routes.ts         # Declarative URL routing table
│   └── server.ts         # Dynamic HTTP request handler
└── shared/
    ├── http.ts           # HTTP client with timeouts and key sanitization
    ├── cache.ts          # In-memory TTL cache
    ├── types.ts          # ToolDefinition, ToolResult, helpers
    ├── resolver.ts       # Ticker/exchange resolution
    └── utils.ts          # withMetadata error wrapper

Licencia

MIT