Fyers MCP Server

Um servidor MCP para a API Fyers v3, com autenticação OAuth automatizada.

GitHub
7
Experimente este MCPPatrocinado

Documentação

Servidor MCP Fyers

Servidor MCP (Model Context Protocol) para a API Fyers v3 com autenticação OAuth automatizada

Python 3.10+ Fyers API v3 License: MIT

Um servidor MCP abrangente que permite ao Claude Desktop interagir com a plataforma de negociação Fyers por meio de um fluxo de autenticação seguro e automatizado. Suporta todas as principais operações de negociação, incluindo gerenciamento de portfólio, colocação de ordens e dados de mercado em tempo real.

🎬 Demonstração

✨ Recursos

🔐 Autenticação Inteligente

  • Fluxo OAuth com um clique com manipulação automática do navegador
  • Armazenamento persistente de tokens no arquivo .env
  • Atualização automática com gerenciamento de sessão

📊 Kit Completo de Negociação

  • Gerenciamento de Portfólio: Posições, ativos, fundos, perfil
  • Gerenciamento de Ordens: Colocar, modificar, cancelar ordens
  • Dados de Mercado: Cotações em tempo real para múltiplos símbolos
  • Histórico de Ordens: Livro completo de ordens e negociações

🚀 Pronto para Produção

  • Tratamento completo de erros com mensagens detalhadas
  • Segurança de tipos com validação de parâmetros
  • Registro abrangente para depuração
  • Integração com Claude Desktop com configuração simples

🚀 Início Rápido

Pré-requisitos

1. Instalação

# Clone the repository
git clone https://github.com/quantabox/fyers-mcp-server.git
cd fyers-mcp-server

# Install dependencies using uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Or install with pip
pip install .

2. Obter Credenciais da API Fyers

  1. Criar Aplicativo na API Fyers:

    • Visite o Painel da API Fyers
    • Crie um novo aplicativo com URI de redirecionamento: http://localhost:8080/
    • Anote seu App ID e Secret Key

  2. Configurar o Ambiente:

    cp .env.example .env

    Edite o arquivo .env:

    FYERS_CLIENT_ID=YOUR_APP_ID-100     # e.g., ABC123XYZ-100
FYERS_SECRET_KEY=YOUR_SECRET_KEY    # Secret from Fyers app
FYERS_REDIRECT_URI=http://localhost:8080/

3. Configurar o Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop:

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

{
  "mcpServers": {
    "fyers-mcp-server": {
      "command": "uv",
      "args": [
        "run", 
        "--directory",
        "/path/to/fyers-mcp-server",
        "python",
        "fyers_mcp_complete.py"
      ],
      "env": {
        "PYTHONWARNINGS": "ignore"
      }
    }
  }
}

4. Primeira Execução

  1. Reinicie o Claude Desktop
  2. Autentique-se: No Claude, digite: authenticate
  3. O navegador abrirá → Faça login na Fyers → Captura automática do token
  4. Comece a negociar: Todas as 11 ferramentas estão agora disponíveis!

🛠️ Ferramentas Disponíveis

Autenticação e Perfil

  • authenticate() - Autenticação OAuth com um clique
  • check_auth_status() - Verificar autenticação atual
  • get_profile() - Informações do perfil do usuário

Portfólio e Fundos

  • get_funds() - Saldo da conta e detalhes de margem
  • get_holdings() - Posições do portfólio com lucro/perda
  • get_positions() - Posições de negociação atuais

Ordens e Negociação

  • place_order(symbol, quantity, order_type, side, ...) - Colocar novas ordens
  • modify_order(order_id, quantity, limit_price, ...) - Modificar ordens existentes
  • cancel_order(order_id) - Cancelar ordens pendentes
  • get_orders() - Histórico e status de ordens

Dados de Mercado

  • get_quotes(symbols) - Cotações em tempo real para múltiplos símbolos

📖 Exemplos de Uso

Análise de Portfólio

# Check account balance
get_funds()

# View all holdings with P&L
get_holdings()

# Check current positions
get_positions()

Gerenciamento de Ordens

# Place a market order
place_order("NSE:SBIN-EQ", 10, "MARKET", "BUY")

# Place a limit order
place_order("NSE:RELIANCE-EQ", 5, "LIMIT", "BUY", limit_price=2500)

# Modify an order
modify_order("ORDER_ID", quantity=15, limit_price=2550)

# Cancel an order
cancel_order("ORDER_ID")

Dados de Mercado

# Get live quotes
get_quotes("NSE:SBIN-EQ,NSE:RELIANCE-EQ,NSE:TCS-EQ")

🔧 Opções de Configuração

Tipos de Ordens

  • MARKET - Ordem de mercado (execução imediata)
  • LIMIT - Ordem limitada (executar a preço específico)
  • STOP - Ordem de stop loss
  • STOPLIMIT - Ordem stop limitada

Tipos de Produtos

  • MARGIN - Negociação com margem (intraday com alavancagem)
  • CNC - Cash and Carry (entrega)
  • INTRADAY - Negociação intraday
  • BO - Ordem de suporte (Bracket Order)
  • CO - Ordem de cobertura (Cover Order)

Opções de Validade

  • DAY - Válido para o dia de negociação atual
  • IOC - Imediato ou Cancelar
  • GTD - Válido até a data

🐛 Solução de Problemas

Problemas Comuns

1. Falha na Autenticação

# Check credentials in .env file
cat .env | grep FYERS

# Verify app configuration at https://myapi.fyers.in/dashboard/

2. Problemas de Conexão com o Claude Desktop

# Test MCP server directly
cd /path/to/fyers-mcp-server
uv run python fyers_mcp_complete.py

# Check Claude Desktop logs (macOS)
tail -f ~/Library/Logs/Claude/mcp.log

3. Erros na Colocação de Ordens

  • Verifique o formato do símbolo: NSE:SYMBOL-EQ para ações
  • Verifique o horário de negociação (9h15 - 15h30 IST)
  • Garanta fundos/margem suficientes

Modo de Depuração

Ative o registro detalhado:

export LOG_LEVEL=DEBUG
uv run python fyers_mcp_complete.py

🚧 Desenvolvimento

Estrutura do Projeto

fyers-mcp-server/
├── fyers_mcp_complete.py    # Main MCP server
├── pyproject.toml          # Dependencies
├── .env.example           # Environment template
├── claude_config.json     # Claude Desktop config
└── README.md             # This file

Adicionando Novos Recursos

  1. Faça um fork do repositório
  2. Crie um branch de recurso: git checkout -b feature/new-tool
  3. Adicione a ferramenta MCP: Use o decorador @mcp.tool()
  4. Teste com o Claude Desktop
  5. Envie uma solicitação de pull

Testes

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Type checking
uv run mypy fyers_mcp_complete.py

📋 Referência da API

Fluxo de Autenticação

graph TD
    A[Claude: authenticate] --> B[Generate Auth URL]
    B --> C[Open Browser]
    C --> D[User Login]
    D --> E[Auth Code Capture]
    E --> F[Exchange for Token]
    F --> G[Store in .env]
    G --> H[Ready for Trading]

Tratamento de Erros

Todas as funções retornam respostas padronizadas:

  • ✅ Sucesso: Confirmação clara com dados relevantes
  • ❌ Erro: Mensagem de erro detalhada com dicas de solução de problemas

🤝 Contribuições

Aceitamos contribuições! Consulte nossas Diretrizes de Contribuição para detalhes.

Áreas para Contribuição

  • Streaming de dados em tempo real via WebSocket
  • Tipos avançados de ordens (OCO, Iceberg)
  • Análise e relatórios de portfólio
  • Ferramentas de análise de cadeia de opções
  • Recursos de gerenciamento de risco

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENÇA para detalhes.

⚠️ Aviso Legal

Este software é para fins educacionais e de desenvolvimento. Negociação envolve risco financeiro. Os usuários são responsáveis por suas decisões de negociação e devem testar minuciosamente em ambientes de demonstração antes da negociação ao vivo.

🔗 Links

📊 Status

  • Versão Atual: 1.0.0
  • Compatibilidade com API: Fyers API v3.1.7
  • Suporte Python: 3.10+
  • Ferramentas Disponíveis: 11/11 ✅
  • Pronto para Produção: Sim ✅

Feito com ❤️ para a comunidade de negociação
Habilite a negociação algorítmica com a inteligência do Claude