Upstox MCP Server

Um servidor do Model Context Protocol (MCP) que se integra à API de Negociação Upstox, permitindo que agentes de IA como o Claude acessem com segurança dados do mercado de ações indiano, realizem análises técnicas e visualizem informações da conta em modo somente leitura.

GitHub

Experimente este MCPPatrocinado

Documentação

Upstox MCP Server: Protocolo de Contexto de Modelo Global para Mercados de Ações Indianos 📈

O Upstox MCP Server de estilo oficial fornece uma integração de alto desempenho do Protocolo de Contexto de Modelo (MCP) para a API de Negociação da Upstox. Ele permite que agentes de IA como Claude Desktop, Cursor IDE e aplicações LLM personalizadas acessem com segurança dados em tempo real do mercado de ações indiano (NSE, BSE, MCX), realizem análises técnicas avançadas (RSI, MACD, Bandas de Bollinger) e gerenciem informações de portfólio em um modo estritamente somente leitura.

Otimizado para negociação algorítmica, análise de mercado e pesquisa automatizada em Nifty 50, Bank Nifty e milhares de ações indianas.

📖 Destaque no Modern AI Day: A Porta USB para IA: Conectando Claude a Dados de Mercado em Tempo Real

🌐 Instância de Demonstração ao Vivo: https://mcp-server-upstox.onrender.com/mcp

🛠️ Stack Técnico

Framework: FastMCP (SDK Python MCP)
Mecanismo de API: FastAPI e Uvicorn
Ciência de Dados: Pandas, NumPy
Análise Técnica: Pandas-TA
Integração de Cliente: Httpx, SDK Python Upstox
Implantação: Docker, Render

⚡ Início Rápido (BYOK Remoto)

Conecte o Claude Desktop à sua instância remota em segundos usando o suporte Bring Your Own Key (BYOK):

{
  "mcpServers": {
    "Upstox-Remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-server-upstox.onrender.com/mcp",
        "--header", "X-Upstox-API-Key:YOUR_API_KEY",
        "--header", "X-Upstox-API-Secret:YOUR_API_SECRET",
        "--header", "X-Upstox-Access-Token:YOUR_ACCESS_TOKEN"
      ]
    }
  }
}

🚀 Recursos

📊 Dados de Mercado

Cotações ao vivo - market_get_live_quote
Buscar Instrumentos - market_search_instruments
Dados históricos - market_get_historical_data (Intervalos personalizados)
Velas intradiárias - market_get_intraday_candles

📈 Análise Técnica

Indicadores Granulares - Ferramentas individuais para RSI, MACD, ADX, Bandas de Bollinger, etc.
Níveis de Fibonacci - analysis_calculate_fibonacci_levels
Padrões de Candlestick - analysis_analyze_candlestick_patterns
Contexto Inteligente - analysis_get_technical_analysis (Super Ferramenta)

👤 Gerenciamento de Conta (Somente Leitura)

Detalhes de Margem - account_get_user_margin
Livro de Ordens - account_get_order_book
Histórico de Negociações - account_get_trade_history
Portfólio - Listas de Posições e Ativos

🤖 Nativo MCP

Design Focado em IA - Construído especificamente para agentes de IA
Arquitetura Baseada em Ferramentas - Linguagem natural para chamadas de API
Suporte Multi-Usuário - Arquitetura segura "Bring Your Own Key" (BYOK)
Interface Conversacional - Sem necessidade de conhecimento complexo de API

⚠️ Aviso de Segurança

Este servidor MCP é ESTRITAMENTE SOMENTE LEITURA
❌ Sem envio de ordens
❌ Sem modificação de ordens
❌ Sem transferências de fundos
❌ Sem ações de negociação

Os endpoints de negociação foram intencionalmente excluídos para sua segurança e proteção.

📦 Instalação

Pré-requisitos

Python 3.10 ou superior
Conta de Negociação Upstox
Credenciais da API Upstox

1️⃣ Clonar Repositório

git clone https://github.com/ravikant1918/mcp-server-upstox.git
cd mcp-server-upstox

2️⃣ Criar Ambiente Virtual (Recomendado)

python -m venv venv

# On macOS/Linux
source venv/bin/activate

# On Windows
venv\Scripts\activate

3️⃣ Instalar Dependências

pip install -e .

4️⃣ Verificar Instalação

upstox-mcp --version

🔐 Configuração

Obtendo Credenciais da API Upstox

Faça login no Console de Desenvolvedor Upstox
- Visite: https://api.upstox.com/
- Faça login com sua conta Upstox
Crie um Aplicativo
- Vá para "My Apps"
- Clique em "Create App"
- Preencha os detalhes:
  - Nome do Aplicativo: "MCP Server"
  - URL de Redirecionamento: http://localhost:8000/callback
  - Selecione permissões somente leitura
Obtenha as Chaves da API
- Anote seu API Key e API Secret
Gere o Token de Acesso
- Siga o fluxo OAuth da Upstox
- Ou use a ferramenta de geração de token da Upstox
- O token é válido por 24 horas (requer renovação diária)

Configuração de Ambiente

Crie um arquivo .env na raiz do projeto:

# Required
UPSTOX_ACCESS_TOKEN=your_access_token_here

# Optional (for token auto-refresh)
UPSTOX_API_KEY=your_api_key
UPSTOX_API_SECRET=your_api_secret

Boas Práticas de Segurança:

Nunca envie o arquivo .env para o controle de versão
Adicione .env ao .gitignore
Rotacione os tokens regularmente
Use apenas escopos de API somente leitura

▶️ Executando o Servidor

Opção A — IO Padrão (para Claude Desktop)

Modo padrão para uso local com agentes de IA:

upstox-mcp
# or
upstox-mcp --transport stdio

Opção B — Modo HTTP (para Cursor ou Acesso Remoto)

Recomendado para agentes de IA baseados na web:

upstox-mcp --transport http
# Server will start on http://localhost:8000

Porta personalizada:

upstox-mcp --transport http --port 8080

Opção C — Implantação com Docker

Usando Docker Compose (Recomendado)

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Usando Docker CLI

# Build image
docker build -t upstox-mcp .

# Run container
docker run -d \
  -p 8000:8000 \
  --env-file .env \
  --name upstox-mcp \
  upstox-mcp

# View logs
docker logs -f upstox-mcp

# Stop container
docker stop upstox-mcp

O servidor estará disponível em: http://localhost:8000/mcp

🔌 Configuração do Cliente MCP

Claude Desktop

Localização da Configuração:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuração:

{
  "mcpServers": {
    "Upstox": {
      "command": "/absolute/path/to/venv/bin/upstox-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "UPSTOX_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Encontrando o caminho absoluto:

# On macOS/Linux
which upstox-mcp

# On Windows (PowerShell)
(Get-Command upstox-mcp).Path

Cursor IDE

Abra as Configurações do Cursor
Vá para Features → MCP
Adicione um novo servidor:
- Nome: Upstox
- Tipo: HTTP
- URL: http://localhost:8000/mcp

MCP Remoto (via mcp-remote) — Suporte BYOK

Para executar o servidor remotamente ou em um ambiente multi-usuário (ex.: Render), você pode passar suas credenciais por meio de cabeçalhos. Isso é conhecido como Bring Your Own Key (BYOK).

{
  "mcpServers": {
    "Upstox-Remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-server-upstox.onrender.com/mcp",
        "--header", "X-Upstox-API-Key:YOUR_API_KEY",
        "--header", "X-Upstox-API-Secret:YOUR_API_SECRET",
        "--header", "X-Upstox-Access-Token:YOUR_ACCESS_TOKEN"
      ]
    }
  }
}

[!TIP] Isso permite que vários usuários usem a mesma instância do servidor com segurança, sem compartilhar credenciais no lado do servidor.

🧠 Exemplos de Prompts (Para Agentes de IA)

Consultas de Dados de Mercado

"What's the current price of RELIANCE?"
"Show me OHLC data for INFY"
"Get live quote for TATAMOTORS on NSE"
"What's the volume on SBIN today?"

Análise Técnica

"Run technical analysis on BHARTIARTL"
"Show RSI and MACD for HDFCBANK"
"Is TCS in a bullish or bearish trend?"
"Find support and resistance levels for WIPRO"
"Analyze ICICIBANK with EMA-20 and EMA-50"

Análise Intradiária

"Show me 5-minute candles for RELIANCE"
"Get 1-minute chart data for INFY"
"Display 15-minute intraday data for SBIN"

Informações da Conta

"Show my Upstox account summary"
"What's my available margin?"
"List all my holdings"
"Show my current positions and P&L"
"What's my total portfolio value?"
"How much profit/loss do I have in TRIDENT?"

Análise Complexa

"Analyze all my holdings technically and rank them by strength"
"Compare HDFC Bank vs ICICI Bank - which is better?"
"Find oversold stocks in my watchlist (RSI < 30)"
"Which of my holdings are above their 50-day EMA?"
"Show me stocks breaking resistance levels today"

🧰 Ferramentas MCP Disponíveis

Categoria	Nome da Ferramenta	Descrição
Mercado	`market_get_live_quote`	Último preço negociado, OHLC, Volume
Mercado	`market_search_instruments`	Buscar símbolos de negociação
Mercado	`market_get_instrument_details`	Metadados detalhados do instrumento
Mercado	`market_get_historical_data`	Dados personalizados de velas históricas
Mercado	`market_get_intraday_candles`	Gráficos intradiários em tempo real
Análise	`analysis_calculate_rsi`	Análise de momentum (RSI)
Análise	`analysis_calculate_macd`	Tendência e momentum (MACD)
Análise	`analysis_calculate_adx`	Força da tendência (ADX)
Análise	`analysis_calculate_moving_averages`	Análise de tendência (SMA/EMA)
Análise	`analysis_calculate_bollinger_bands`	Estudo de volatilidade
Análise	`analysis_calculate_support_resistance`	Níveis baseados em pivô
Análise	`analysis_calculate_volatility_metrics`	Avaliação de risco (ATR)
Análise	`analysis_calculate_stochastic`	Oscilador de momentum
Análise	`analysis_calculate_williams_r`	Momentum %R
Análise	`analysis_calculate_fibonacci_levels`	Níveis de retração
Análise	`analysis_analyze_candlestick_patterns`	Detecção de padrões
Análise	`analysis_get_technical_analysis`	Relatório holístico multi-indicador
Conta	`account_get_summary`	Instantâneo do portfólio
Conta	`account_get_user_margin`	Fundos disponíveis
Conta	`account_get_holdings_list`	Ativos em ações
Conta	`account_get_positions_list`	Posições ativas
Conta	`account_get_order_book`	Ordens diárias
Conta	`account_get_trade_history`	Execuções diárias

[!NOTE] Todas as ferramentas retornam uma resposta JSON padronizada: { "success": true, "data": ..., "error": null, "metadata": ... }.

Detalhes das Ferramentas

`get_live_quote`

{
  "symbol": "RELIANCE",      # Stock symbol
  "exchange": "NSE_EQ"       # NSE_EQ or BSE_EQ (default: NSE_EQ)
}

`get_intraday_candles`

{
  "symbol": "INFY",
  "interval": "5minute",     # 1minute, 3minute, 5minute, 10minute, 15minute, 30minute
  "exchange": "NSE_EQ"
}

`get_technical_analysis`

{
  "symbol": "SBIN",
  "interval": "1day",        # 1minute, 5minute, 15minute, 30minute, 1day, 1week
  "indicators": [            # Array of indicators
    "RSI",                   # Relative Strength Index
    "MACD",                  # Moving Average Convergence Divergence
    "EMA_20",                # Exponential Moving Average (20 period)
    "EMA_50",
    "SMA_200",               # Simple Moving Average (200 period)
    "BBANDS",                # Bollinger Bands
    "VWAP",                  # Volume Weighted Average Price
    "ATR"                    # Average True Range
  ],
  "exchange": "NSE_EQ"
}

Indicadores Suportados:

RSI - Oscilador de momentum (padrão de 14 períodos)
MACD - Indicador de acompanhamento de tendência
EMA_x - Média Móvel Exponencial (ex.: EMA_20, EMA_50, EMA_200)
SMA_x - Média Móvel Simples (ex.: SMA_50, SMA_200)
BBANDS - Bandas de Bollinger (volatilidade)
VWAP - Preço Médio Ponderado por Volume
ATR - Average True Range (volatilidade)

Retorna:

Dados de preço
Indicadores calculados
Padrões de candlestick detectados
Contexto de tendência (Alta/Baixa/Lateral)
Níveis de suporte e resistência

🏗️ Arquitetura

┌─────────────────┐
│   AI Agent      │  (Claude Desktop, Cursor, etc.)
│  (Claude/GPT)   │
└────────┬────────┘
         │
         │ MCP Protocol
         │
┌────────▼────────┐
│   FastMCP       │  (MCP Server Framework)
│   Server        │
└────────┬────────┘
         │
         │ Python Functions
         │
┌────────▼────────┐
│   Upstox API    │  (Read-Only Access)
│   Client        │
└────────┬────────┘
         │
         │ HTTPS
         │
┌────────▼────────┐
│   Upstox        │  (Live Market Data)
│   Backend       │
└─────────────────┘

📊 Stack Técnico

Framework: FastMCP (Model Context Protocol)
Cliente de API: SDK Python Upstox
Análise Técnica: pandas-ta
Servidor Web: Uvicorn (para modo HTTP)
Containerização: Docker, Docker Compose

🔧 Solução de Problemas

Problemas Comuns

1. Erro "Invalid token"

Problema: Token de acesso expirado (tokens são válidos por 24 horas)

Solução:

# Generate new token from Upstox
# Update .env file with new token
# Restart the MCP server

2. "Command not found: upstox-mcp"

Problema: Pacote não instalado ou não está no PATH

Solução:

# Activate virtual environment
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Reinstall package
pip install -e .

3. Claude Desktop Não Detecta o Servidor

Problema: Caminho do arquivo de configuração ou problema de formato

Solução:

Verifique a localização do arquivo de configuração
Verifique a sintaxe JSON (use um validador JSON)
Garanta o caminho absoluto para o executável
Reinicie o Claude Desktop

4. "No data returned" para Velas Intradiárias

Problema: Mercado fechado ou sem atividade de negociação recente

Solução:

Verifique se o mercado está aberto (9:15 - 15:30 IST, seg-sex)
Tente um intervalo diferente
Verifique se o símbolo está correto

5. Limitação de Taxa

Problema: Muitas chamadas de API em pouco tempo

Solução:

Adicione atrasos entre as solicitações
Implemente cache (melhoria futura)
Use consultas em lote quando possível

🚧 Limitações

Expiração do Token: Tokens de acesso expiram a cada 24 horas e precisam de renovação manual
Somente Leitura: Não é possível realizar negociações (por design, para segurança)
Limites de Taxa da API: Sujeito à limitação de taxa da API Upstox
Horário de Mercado: Dados ao vivo disponíveis apenas durante o horário de negociação
Dados Históricos: Limitado pelas políticas de retenção de dados da API Upstox

🗺️ Roadmap

Versão 1.1 (Concluída)

Camada de cache para melhor desempenho
Detecção básica de padrões de candlestick

Versão 2.0 (Concluída) 🚀

Indicadores Técnicos Granulares: 10+ novas ferramentas especializadas de TA
Ferramentas com Namespaces: Agrupamento lógico (market_, analysis_, account_)
Dados Históricos: Recuperação com intervalos de tempo personalizados
Busca de Instrumentos: Encontre símbolos por nome
Esquema de Resposta Seguro para JSON: Serialização robusta para todos os agentes
Rastreamento de Ordens e Negociações: Acesso em tempo real à atividade diária

Versão 2.1 (Concluída) 🚀

Suporte BYOK: Passe credenciais por meio de cabeçalhos HTTP
Suporte Multi-Usuário: Arquitetura segura para implantações compartilhadas
Instruções Dinâmicas: Página inicial interativa com guias de configuração

Versão 3.0 (Planejada)

Mecanismo automático de renovação de token
Integração com banco de dados para rastreamento histórico de longo prazo
Análises de desempenho do portfólio
Sistema de alertas
Previsões com aprendizado de máquina

Versão 3.0 (Visão)

Previsões com aprendizado de máquina
Construtor de estratégias
Recursos de negociação social
Integração com aplicativo móvel

🤝 Contribuindo

Contribuições são bem-vindas! Siga estes passos:

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/AmazingFeature)
Faça commit das suas alterações (git commit -m 'Add some AmazingFeature')
Envie para o branch (git push origin feature/AmazingFeature)
Abra um Pull Request

Configuração de Desenvolvimento

# Clone your fork
git clone https://github.com/ravikant1918/mcp-server-upstox.git

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
flake8 .

🗺️ Roadmap

Q1 2026: Fundação e Análise Principal (Atual)

Implementação inicial do MCP para Upstox
Ferramentas abrangentes de indicadores técnicos
Suporte Bring Your Own Key (BYOK) para implantações remotas
Gerador dinâmico de configuração JSON

Q2 2026: Insights Avançados

Ferramentas de análise de mercado por setor
Análise de Option Chain (cálculo de Gregas)
Rastreamento de ações corporativas (Dividendos, Desdobramentos)
Análise de correlação multi-instrumento

Q3 2026: Expansão do Ecossistema

Wrapper integrado de mecanismo de backtesting
Suporte a webhooks para alertas em tempo real
Suporte nativo para mais clientes MCP (ex.: Goose, Windsurf)

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🙌 Créditos e Agradecimentos

FastMCP - Framework de servidor MCP
Upstox - API de negociação e dados de mercado
pandas-ta - Indicadores de análise técnica
Anthropic - Claude AI e protocolo MCP

📬 Aviso Legal

IMPORTANTE: Este projeto não é afiliado, endossado ou patrocinado pela Upstox.

Aviso de Negociação:

Negociar ações envolve risco substancial de perda
Esta ferramenta é apenas para fins informativos e educacionais
Não é aconselhamento financeiro - consulte um consultor financeiro licenciado
Desempenho passado não garante resultados futuros
Os desenvolvedores não são responsáveis por quaisquer perdas de negociação
Sempre faça sua própria pesquisa antes de tomar decisões de investimento

Uso da API:

Garanta conformidade com os termos de serviço da API Upstox
Respeite os limites de taxa da API
Use de forma responsável e ética

📞 Suporte

Documentação

Obter Ajuda

Problemas: Issues do GitHub
Discussões: Discussões do GitHub
E-mail: developerrk1918@gmail.com

Comunidade

Dê uma estrela ⭐ neste repositório se você achar útil
Compartilhe com outros traders
Reporte bugs e sugira funcionalidades
Contribua com código ou documentação

🎯 Resumo de Início Rápido

# 1. Clone and install
git clone https://github.com/ravikant1918/mcp-server-upstox.git
cd mcp-server-upstox
pip install -e .

# 2. Configure
echo "UPSTOX_ACCESS_TOKEN=your_token" > .env

# 3. Run
upstox-mcp

# 4. Use with Claude
# Add to Claude Desktop config, restart, and start chatting!

Feito com ❤️ para Traders Indianos

Boas negociações! 📈🚀