stock-scanner

stock-scanner-mcp

Um servidor MCP modular para Claude Code e Claude Desktop que fornece acesso em tempo real a dados de ações e criptomoedas. Varra mercados, verifique indicadores técnicos, monitore negociações de insiders, acompanhe resultados, analise fluxo de opções e, opcionalmente, salve suas próprias listas de observação e notas de tese em um único servidor.

69 ferramentas em 15 módulos — 11 módulos funcionam sem chaves de API, incluindo um Workspace de Mercado opcional com estado.

Início Rápido

Três passos para ter a experiência completa: configuração do servidor, habilidades de trading e configuração do workspace.

Passo 1 — Adicione o servidor à sua configuração MCP

Copie este bloco de configuração completo para o seu arquivo de configuração:

• Claude Code: ~/.claude.json (global) ou .mcp.json (local ao projeto)
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %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"
      }
    }
  }
}

Isso lhe dá 49 ferramentas imediatamente, sem chaves de API. As chaves de API são opcionais e gratuitas — elas desbloqueiam 20 ferramentas adicionais para cotações em tempo real, notícias, resultados e dados econômicos. Veja API Keys abaixo para saber onde obtê-las.

Configuração mínima — se você não quiser workspace ou chaves de API, use isto:

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

Isso lhe dá 42 ferramentas sem estado sem armazenamento local de dados.

Reinicie o Claude Desktop após salvar. O Claude Code detecta a configuração automaticamente.

Atalho para Claude Code — instale como plugin em vez dos Passos 1 e 2. Se você usa Claude Code, pule a configuração manual acima e instale tudo com dois comandos:

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

Execute /reload-plugins e depois /mcp — você deve ver o servidor stock-scanner listado como conectado. O primeiro lançamento executa npx -y stock-scanner-mcp, que baixa o pacote uma vez (depois fica em cache). O plugin ativa o workspace por padrão (os dados são armazenados em ~/.stock-scanner-mcp) e repassa as chaves de API opcionais (FINNHUB_API_KEY, ALPHA_VANTAGE_API_KEY, FRED_API_KEY) do seu ambiente; módulos sem chave são ignorados automaticamente.

O plugin já inclui as habilidades — NÃO execute o Passo 2. Todas as 19 habilidades acompanham o plugin e carregam sob o namespace stock-scanner:, por exemplo, /stock-scanner:analyze-stock AAPL, /stock-scanner:morning-briefing, /stock-scanner:setup-market-workspace. Executar o instalador do Passo 2 também copia um segundo conjunto sem prefixo para ~/.claude/skills/, e os dois entram em conflito — o Passo 2 é apenas para a instalação manual (sem plugin). Após instalar, vá direto ao Passo 3, usando o comando com namespace: /stock-scanner:setup-market-workspace.

Passo 2 — Instale as habilidades de trading

Pule este passo se você instalou via plugin acima — o plugin já inclui essas habilidades (como stock-scanner:<name>). Este passo é apenas para a configuração manual do Passo 1.

Execute este comando no seu terminal:

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

Isso instala 19 comandos de barra (como /morning-briefing, /analyze-stock AAPL, /setup-market-workspace) em ~/.claude/skills/ para que fiquem disponíveis em todas as sessões do Claude Code. Veja Trading Skills para a lista completa.

Passo 3 — Configure seu workspace

Execute /setup-market-workspace no Claude Code. Ele faz três perguntas 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"

Após responder, ele salva seu perfil e cria uma lista de observação core:

✓ Workspace saved

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

Você também pode pular a habilidade e pedir diretamente ao Claude: "Configure meu workspace — sou um swing trader, crie uma lista de observação principal com MARA, HOOD, BTC, revisões diárias."

É isso. Agora você tem 69 ferramentas, 19 habilidades e um workspace personalizado. Experimente /workspace-morning-brief para sua primeira varredura de mercado personalizada.

O Que Você Pode Fazer

"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"

Destaques

• Varredura de ações — filtre por preço, RSI, volume, capitalização de mercado com filtros personalizados
• Análise técnica — RSI, MACD, Bandas de Bollinger, médias móveis, pivôs em múltiplos períodos
• Fluxo de opções — cadeias com Gregos, detecção de atividade incomum, max pain, movimento implícito
• Negociações de insiders — transações do Formulário 4 analisadas com detalhes de compra/venda/doação
• Resultados e notícias — calendário, classificações de analistas, notícias de empresas, juros sobre vendas a descoberto
• Cripto — cotações em tempo real, indicadores técnicos, moedas em alta, estatísticas de mercado
• Macro — IPCA, PIB, taxa de juros federal, calendário econômico, dados da curva de juros
• Forex — 31 pares de moedas do BCE, conversão, taxas históricas
• Sentimento — Índice de Medo e Ganância da CNN, Medo e Ganância de Cripto
• Workspace de Mercado — salve um perfil de trading, listas de observação nomeadas e notas de tese para fluxos de trabalho personalizados entre sessões

Habilidades de Trading

19 fluxos de trabalho prontos que encadeiam múltiplas ferramentas em análises estruturadas. Cada habilidade orquestra 5 a 14 ferramentas em paralelo e gera um veredito com direção, confiança e níveis-chave.

As habilidades degradam graciosamente quando chaves de API opcionais estão ausentes. As habilidades do workspace exigem --enable-workspace na configuração do 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

Veja skills/README.md para o catálogo completo.

Workspace de Mercado

O Workspace de Mercado é uma camada opcional com estado que lembra seu contexto de trading entre sessões — seu estilo de trading, listas de observação nomeadas e notas de tese de investimento por símbolo. Habilidades como /workspace-morning-brief usam esse contexto para entregar varreduras de mercado personalizadas em vez de genéricas.

O que você pode fazer com ele

• /workspace-morning-brief — varredura pré-mercado personalizada que lê seu perfil e lista de observação, verifica resultados, notícias e ação de preço dos seus ativos, e destaca o que importa hoje
• Adicionar mais listas de observação — peça ao Claude: "Crie uma lista de observação chamada 'resultados' com AAPL, MSFT, GOOG"
• Acompanhar teses de investimento — salve seu raciocínio por ticker para que o sistema monitore por você (veja abaixo)
• Atualizar a qualquer momento — "Adicione NVDA à minha lista de observação principal" ou "Mude minha cadência de revisão para semanal"

Acompanhamento de Teses

Salve seu raciocínio de investimento por ticker — direção, níveis-chave, catalisadores e período — para que o sistema possa monitorá-lo entre sessões.

Salvar uma tese:

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

O Claude salva a tese estruturada:

Como funciona na prática: Quando você executa /workspace-morning-brief, o briefing cruza suas teses salvas com a ação de preço ao vivo:

• NIO cai para $6,10 → "NIO rompeu abaixo do seu piso de tese de $6,35 — reavalie."
• NIO sobe para $7,20 → "NIO mantendo acima do seu nível de $6,35 — tese de alta intacta."

Sem uma tese, o briefing apenas relata uma mudança de preço. Com uma tese, ele informa se o movimento importa para o seu plano.

Cada tese suporta cinco campos: summary, bullCase, bearCase, catalyst e timeframe. Você pode salvar até 200 teses por workspace.

Referência de configuração

Os dados são armazenados localmente em workspace.json — sem sincronização em nuvem, sem chamadas externas. Se você omitir --enable-workspace, o servidor permanece totalmente sem estado e não grava dados locais.

Para a lista completa de ferramentas do workspace, veja a referência de ferramentas abaixo.

Documentação

• Instalação e Configuração — Como colocar o servidor MCP em funcionamento no Claude Code ou Cursor
• Habilidades de Trading — Fluxos de trabalho prontos para análise profissional
• API HTTP Sidecar — Endpoints REST para clientes não-MCP
• Implantação com Docker — Executando em contêineres com persistência de workspace
• FAQ e Solução de Problemas — Problemas comuns e soluções

Módulos

Os módulos são ativados automaticamente quando sua chave de API é definida. Módulos sem chave estão sempre ativados, exceto workspace, que requer --enable-workspace.

Para uma lista completa de todas as ferramentas com descrições, veja a Referência Completa de Ferramentas abaixo.

Referência Completa de Ferramentas (69 ferramentas)

TradingView — Varredura de Ações (sem chave de API)

TradingView — Cripto (sem chave de API)

SEC EDGAR — Documentos e Participação (sem chave de API)

CoinGecko — Inteligência de Cripto (sem chave de API)

Opções — Cadeias, Gregas e Atividade Incomum (sem chave de API)

Opções CBOE — Sentimento Put/Call (sem chave de API)

Sentimento — Fear & Greed (sem chave de API)

Frankfurter — Taxas Forex (sem chave de API)

Reddit — Tickers em Alta e Sentimento (sem chave de API)

Amplitude de Mercado — Indicadores de Amplitude (sem chave de API)

Mercado Unificado — Roteamento Inteligente (sem chave de API)

Workspace — Contexto Personalizado (opcional, sem chave de API)

Habilitado apenas quando você inicia o servidor com --enable-workspace.

Finnhub — Notícias, Resultados e Macro (requer FINNHUB_API_KEY)

Alpha Vantage — Fundamentos e Histórico (requer ALPHA_VANTAGE_API_KEY)

FRED — Dados Econômicos dos EUA (requer FRED_API_KEY)

Configuração

Opções 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

Chaves de API (opcional)

Todas as três chaves são gratuitas — não é necessário cartão de crédito:

Adicione-as ao bloco env na sua configuração MCP (veja Início Rápido).

Uso com outros clientes MCP

Qualquer cliente MCP que suporte servidores stdio pode executar este pacote. Use a mesma configuração JSON do Início Rápido. Se o seu cliente não expõe npx, instale o pacote primeiro e aponte o cliente para o binário instalado.

HTTP Sidecar

Um servidor HTTP opcional que expõe todas as ferramentas como endpoints REST para integrações não-MCP (GPT Actions, UIs de chat, pipelines de LLM). Inclui uma especificação OpenAPI 3.1 para descoberta automatizada de ferramentas.

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

Veja API HTTP do Sidecar para detalhes dos endpoints.

69 ferramentas expostas como rotas REST, incluindo /market/quote, /options/chain, /workspace/profile e mais.

Limites de Requisições

Todos os módulos usam cache TTL em memória para minimizar chamadas de API.

Desenvolvimento

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

Artefatos de Credibilidade

• Exemplos de benchmark
• Transcrições de exemplo
• Instantâneo de latência e confiabilidade

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

Licença

MIT