Stock Market Tracker

Servidor MCP para análise financeira avançada, monitoramento de ações e inteligência de mercado em tempo real para apoiar decisões de compra/venda.

GitHub
1

Documentação

Financial MCP Server

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

Azure / Render / GCP Cloud Run hospedam o backend MCP · Cloudflare implanta o proxy HTTPS opcional

Um servidor personalizado de Model Context Protocol (MCP) para análise financeira avançada, monitoramento de ações e inteligência de mercado em tempo real. Este servidor fornece um conjunto de ferramentas e endpoints de API para gerenciamento de portfólio, resumos de mercado, alertas de ações e insights financeiros contextuais, projetado para integração perfeita com o Claude Desktop e outros clientes compatíveis com MCP.

Implantação em Nuvem com Um Clique

Use os botões no topo desta página ou o guia completo em DEPLOY.md para iniciar um endpoint MCP remoto em https://<host>/mcp.

PlataformaImplantaAutenticação padrãoConfiguração OAuth
Azure Container AppsBackend Python MCP (azuredeploy.json)mcpAuthMode=staticDefina mcpAuthMode=oauth + configurações do Entra no portal — veja OAuth (Entra ID)
RenderBackend Python MCP (render.yaml)MCP_AUTH_MODE=staticDefina MCP_ACCESS_TOKEN (obrigatório no modo estático) e adicione variáveis de ambiente OAuth no painel do Render, se necessário
Google Cloud RunBackend Python MCP (Dockerfile / GHCR)MCP_AUTH_MODE=staticDefina as variáveis de ambiente OAuth no Cloud Run → Variables & secrets — veja gcp/README.md
Cloudflare WorkerApenas proxy HTTPS (cloudflare-worker/)WORKER_AUTH_MODE=staticUse WORKER_AUTH_MODE=passthrough quando o backend usar JWTs OAuth
  • Padrão local: MCP_TRANSPORT=stdio (Claude Desktop / clientes MCP locais)
  • Padrão em nuvem: MCP_TRANSPORT=streamable-http
  • Modos de autenticação: MCP_AUTH_MODE=static|oauth|none — o client ID/secret OAuth ficam no Claude, não no servidor

Principais Recursos

  • Kit de Ferramentas de Ações: Ferramentas de cotações, visão geral da empresa e histórico de preços para fluxos de trabalho práticos de análise.
  • Portfólio com Valores em Tempo Real: Mantenha um armazenamento de watchlist/posições e retorne contexto de avaliação em nível de portfólio.
  • Alertas de Preço Configuráveis: Defina limites above / below por ticker e avalie eventos de alerta acionados.
  • Camada de Notícias + Contexto: Recupere notícias de mercado e resumos contextuais opcionais com análise de sentimento para fluxos de pesquisa.
  • HTTP Streamable Seguro: Bearer estático (MCP_ACCESS_TOKEN) ou validação JWT OAuth (MCP_AUTH_MODE=oauth) para implantações públicas.
  • Implantação Pronta para Nuvem: Docker + implantações com um clique para Azure Container Apps, Render, Google Cloud Run e proxy Cloudflare Worker.

Visão Geral do Sistema

Endpoints e Ferramentas Principais

  • get_stock_quote(ticker: str)
    • Retorna dados de cotação ao vivo normalizados (preço, variação, capitalização de mercado, volume, bolsa, timestamp).
  • get_price_history(ticker: str, period: str, interval: str)
    • Retorna pontos de histórico OHLCV prontos para gráficos, para backtesting e análise de tendências.
  • get_company_overview(ticker: str)
    • Retorna metadados do perfil da empresa e campos-chave de avaliação quando disponíveis.
  • get_portfolio()
    • Retorna posições/watchlist, além de enriquecimento de cotações ao vivo e resumo do valor de mercado do portfólio.
  • add_stock(...) / remove_stock(...)
    • Adiciona ou remove símbolos no armazenamento persistente do portfólio.
  • set_stock_alert(ticker, above=None, below=None) / get_portfolio_alerts(ticker=None)
    • Configura e avalia alertas de limite de preço a partir de regras baseadas no portfólio.
  • get_stock_news(ticker_or_query, max_results=5) e financial_context(query)
    • Fornece manchetes financeiras brutas e resumos contextuais opcionais prontos para LLM.

Alertas Automatizados

  • Integração com Telegram: Envia alertas e resumos formatados para um chat do Telegram configurado.
  • Oportunidades de Trading: Detecta e notifica sobre sinais de trading acionáveis.

Resumo Contextual

  • Resumidor de Notícias: Usa backends LLM configuráveis (ollama, openai ou auto) para gerar resumos detalhados com tags de sentimento.
  • Construtor de Prompt: Constrói um prompt com consciência de mercado para uso em LLMs ou assistentes downstream.

Estrutura de Arquivos

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

Configuração e Personalização

Configuração de Alertas (config/alerts_config.json)

  • Organize ações por setor, com limites de preço superiores/inferiores personalizáveis e descrições.
  • Exemplo de estrutura:
{
  "Tech Giants": {
    "AAPL": {"above": 200, "below": 180, "description": "Apple Inc."}
  },
  "Financial": {
    "JPM": {"above": 160, "below": 140, "description": "JPMorgan Chase"}
  }
}

Variáveis de Ambiente

Defina estas em um arquivo .env ou no ambiente do seu 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 Autenticação HTTP

  • static: valida um único bearer token (MCP_ACCESS_TOKEN). Deixe MCP_RESOURCE_SERVER_URL não definido para que o servidor não publique metadados de recursos protegidos OAuth (recomendado para Postman e configuração simples de bearer no Claude).
  • oauth: valida tokens de acesso JWT de um provedor OIDC externo usando OAUTH_ISSUER_URL + OAUTH_AUDIENCE (+ OAUTH_JWKS_URL opcional). O OAUTH_ISSUER_URLS opcional permite emissores confiáveis adicionais (por exemplo, sts.windows.net quando o Entra retorna claims de emissor v1). O client ID e o client secret pertencem ao app conector / IdP, não a este servidor.
  • none: apenas para testes locais com ALLOW_UNAUTHENTICATED_HTTP=true.

Microsoft Entra ID (Azure AD)

Para conectores OAuth do Claude, registre um API app do Entra e um client app separado, implante o backend com MCP_AUTH_MODE=oauth e configure o Claude com as credenciais do client app.

Configuração passo a passo do Entra e do Claude: DEPLOY.md — OAuth (Entra ID).

Se o Claude continuar falhando com AADSTS9010010 do Entra enquanto o Postman funciona com o mesmo token, habilite o broker integrado descrito em DEPLOY.md — OAuth Broker For Claude + Entra.

Instalação e Execução a partir do Claude Desktop

Pré-requisitos

  • Python 3.7+
  • Claude Desktop (ou qualquer cliente compatível com MCP)
  • Credenciais do bot do Telegram (para alertas)
  • Conexão com a internet (para dados de mercado/notícias)

Guia Passo a Passo

  1. Clone o Repositório

    git clone <this-repo-url>
cd Finance_MCP_Server

  2. Crie e Ative um Ambiente Virtual

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

  3. Instale as Dependências

    pip install -r requirements.txt

  4. Configure as Variáveis de Ambiente

    • Crie um arquivo .env na raiz do projeto com suas chaves de API e 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. Edite as Configurações de Alertas

    • Modifique config/alerts_config.json e config/tech_alerts_config.json para definir suas ações, setores e limites.

  6. Instale o Servidor MCP com a CLI

    • Use a CLI do MCP para instalar e registrar o servidor para o Claude Desktop: 
      mcp install server.py --name "Financial MCP Server"
    • Isso registrará o servidor como uma ferramenta MCP personalizada, tornando-a detectável pelo Claude Desktop e outros clientes MCP.

  7. Execute o Servidor MCP via CLI do MCP

    • Inicie o servidor usando a CLI do MCP: 
      mcp run server.py
    • O servidor iniciará e aguardará solicitações MCP via stdio.

  8. Conecte-se a partir do Claude Desktop

    • No Claude Desktop, adicione uma nova conexão de servidor MCP personalizado.
    • Defina o executável/comando como mcp run server.py (ou selecione o "Financial MCP Server" registrado na lista da CLI do MCP).
    • O Claude Desktop se comunicará com o servidor usando o protocolo MCP, habilitando todas as ferramentas e endpoints descritos.

Exemplo: Configuração do Servidor MCP no Claude Desktop

Após instalar e registrar o Financial MCP Server, você pode adicioná-lo à configuração do seu Claude Desktop. Aqui está um exemplo de trecho 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": ""
      }
    }
  }
}
  • Atualize a seção env com suas chaves de API e tokens reais, conforme necessário.
  • Esta configuração garante que o Claude Desktop possa iniciar e se comunicar com seu Financial MCP Server usando o ambiente e os argumentos de linha de comando corretos.

Usando Suas Ferramentas no Claude Desktop

Após instalar e conectar seu Financial MCP Server personalizado, todas as ferramentas disponíveis aparecerão automaticamente no menu de ferramentas do Claude Desktop. Você pode habilitar ou desabilitar cada ferramenta individualmente, facilitando o acesso a funcionalidades como análise de contexto financeiro, resumos de mercado, gerenciamento de portfólio e alertas de ações diretamente da interface do Claude.

Abaixo está uma captura de tela mostrando como as ferramentas do seu servidor MCP serão listadas e alternadas no Claude Desktop:

Claude Desktop MCP Tools Example

  • Cada ferramenta (por exemplo, financial_context, market_summary, add_stock, etc.) pode ser habilitada ou desabilitada conforme necessário.
  • Essa integração perfeita permite que você interaja com seu servidor de análise financeira usando linguagem natural e fluxos de trabalho baseados em ferramentas dentro do Claude Desktop.

Exemplos de Uso

  • Obter Cotações ao Vivo: Use get_stock_quote e get_company_overview para verificações práticas de ações.
  • Acompanhar Portfólio: Use add_stock, remove_stock e get_portfolio para manter e avaliar sua watchlist.
  • Avaliar Alertas: Use set_stock_alert e get_portfolio_alerts para sinais baseados em limites.
  • Análise Contextual: Use financial_context para buscar e resumir o contexto de mercado para uma consulta.

Solução de Problemas e Logs

  • Todos os logs são gravados em financial_mcp.log na raiz do projeto.
  • Para depuração, verifique o arquivo de log e certifique-se de que suas variáveis de ambiente e arquivos de configuração estejam corretos.
  • Se você encontrar problemas com o Telegram ou com a busca de notícias, verifique suas chaves de API e sua conexão com a internet.