Shioaji MCP Server

Acesse a API de negociação Shioaji para dados financeiros e operações de trading, exigindo uma conta na SinoPac Securities.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Servidor MCP Shioaji

Fornece um servidor de Protocolo de Contexto de Modelo (MCP) para os recursos da API de negociação Shioaji da Yuanta Securities, acessando funcionalidades de negociação por meio de ferramentas padronizadas.

Chinês Tradicional | English

Recursos

Autenticação e Conexão

  • get_account_info - Obter informações da conta e status da conexão

Dados de Mercado

  • search_contracts - Buscar contratos de negociação por palavra-chave, bolsa ou categoria
  • get_snapshots - Obter snapshots de mercado em tempo real para contratos especificados
  • get_kbars - Obter dados históricos de candles para contratos

Operações de Negociação

  • place_order - Enviar ordens de compra/venda com parâmetros especificados (requer permissão)
  • cancel_order - Cancelar ordens existentes por ID da ordem (requer permissão)
  • list_orders - Listar todas as ordens e seus status
  • get_positions - Obter posições atuais e lucros/perdas (suporta ações, futuros ou todas as contas)
  • get_account_balance - Obter saldos da conta e informações de margem (suporta ações, futuros ou todas as contas)

⚠️ Segurança de Negociação: Operações de negociação (place_order, cancel_order) estão desabilitadas por padrão. Defina SHIOAJI_TRADING_ENABLED=true para habilitar funcionalidades de negociação.

Termos de Serviço e Conformidade

  • check_terms_status - Verificar status de assinatura dos termos de serviço e conclusão dos testes de API
  • run_api_test - Executar testes de API para conformidade dos termos de serviço (testes de login e ordens)

Pré-requisitos

  1. Conta Yuanta Securities: Você precisa de uma conta Yuanta Securities
  2. Credenciais de API: Solicite e obtenha a Chave de API e a Chave Secreta
  3. Termos de Serviço: Complete a assinatura de documentos e testes de API (veja docs/SERVICE_TERMS.md)

Para detalhes sobre imagens Docker usando GitHub Container Registry, consulte docs/CONTAINER_REGISTRY.md.

Instalação e Uso

Usando a imagem Docker pré-construída (recomendado)

Usar a imagem Docker pré-construída do GitHub Container Registry é a maneira mais simples:

# 拉取最新穩定版映像
docker pull ghcr.io/musingfox/shioaji-mcp:latest

# 執行 MCP 伺服器（唯讀模式）
docker run --rm -i --platform=linux/amd64 \
  -e SHIOAJI_API_KEY=your_api_key \
  -e SHIOAJI_SECRET_KEY=your_secret_key \
  -e SHIOAJI_TRADING_ENABLED=false \
  ghcr.io/musingfox/shioaji-mcp:latest

# 執行 MCP 伺服器並啟用交易功能
docker run --rm -i --platform=linux/amd64 \
  -e SHIOAJI_API_KEY=your_api_key \
  -e SHIOAJI_SECRET_KEY=your_secret_key \
  -e SHIOAJI_TRADING_ENABLED=true \
  ghcr.io/musingfox/shioaji-mcp:latest

Tags disponíveis

  • latest - Versão estável mais recente do branch principal
  • vX.Y.Z (como v0.1.0) - Lançamentos de versões específicas
  • dev - Versão de desenvolvimento mais recente (pode conter recursos experimentais)

Recomenda-se usar tags de versões específicas em produção.

Construindo a imagem Docker localmente

Se preferir construir a imagem localmente:

# 建置 Docker 映像
docker build -t shioaji-mcp .

# 執行 MCP 伺服器（唯讀模式）
docker run --rm -i --platform=linux/amd64 \
  -e SHIOAJI_API_KEY=your_api_key \
  -e SHIOAJI_SECRET_KEY=your_secret_key \
  -e SHIOAJI_TRADING_ENABLED=false \
  shioaji-mcp

Configuração do cliente MCP

Adicione a seguinte configuração ao seu cliente MCP:

{
  "mcpServers": {
    "shioaji": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--platform=linux/amd64",
        "-e", "SHIOAJI_API_KEY=your_api_key",
        "-e", "SHIOAJI_SECRET_KEY=your_secret_key",
        "-e", "SHIOAJI_TRADING_ENABLED=false",
        "ghcr.io/musingfox/shioaji-mcp:latest"
      ]
    }
  }
}

Permissões de negociação:

  • Defina SHIOAJI_TRADING_ENABLED=false (padrão) para modo somente leitura
  • Defina SHIOAJI_TRADING_ENABLED=true para habilitar operações de negociação

Exemplo com negociação habilitada:

"-e", "SHIOAJI_TRADING_ENABLED=true"

Para desenvolvimento ou testes, você pode usar a tag dev:

"ghcr.io/musingfox/shioaji-mcp:dev"

Exemplo de cliente Python

Fornecemos um exemplo de cliente Python demonstrando como usar o servidor MCP Shioaji programaticamente:

# 安裝 MCP 客戶端程式庫
pip install mcp-client

# 設定您的 API 憑證
export SHIOAJI_API_KEY=your_api_key
export SHIOAJI_SECRET_KEY=your_secret_key

# 執行範例
./examples/python_client.py

O exemplo demonstra:

  • Conectar ao servidor MCP Shioaji
  • Obter informações da conta
  • Buscar contratos
  • Obter dados de mercado em tempo real
  • Obter dados históricos de candles
  • Recuperar posições e saldos da conta

Veja o código completo em examples/python_client.py.

Desenvolvimento local (Linux/WSL)

# 複製專案
git clone <repository-url>
cd shioaji-mcp

# 安裝相依套件
uv sync

# 設定環境變數
export SHIOAJI_API_KEY=your_api_key
export SHIOAJI_SECRET_KEY=your_secret_key

# 執行 MCP 伺服器
uv run python -m shioaji_mcp.server

Guia de Desenvolvimento

Configuração do ambiente

# 安裝開發相依套件
uv sync --extra dev

# 設定環境變數（如需本地開發）
export SHIOAJI_API_KEY=your_api_key
export SHIOAJI_SECRET_KEY=your_secret_key

Testes

# 執行測試
uv run pytest

# 測試覆蓋率
uv run pytest --cov=src/shioaji_mcp

Qualidade do código

# 檢查和格式化程式碼
uv run ruff check --fix src/ tests/
uv run ruff format src/ tests/

# 型別檢查
uv run mypy src/

Desenvolvimento com Docker

# 建置開發 Docker 映像
docker build -t shioaji-mcp-dev .

# 測試 Docker 容器
docker run --rm -i --platform=linux/amd64 \
  -e SHIOAJI_API_KEY=test_key \
  -e SHIOAJI_SECRET_KEY=test_secret \
  shioaji-mcp-dev

Arquitetura

src/shioaji_mcp/
├── server.py          # MCP 伺服器主程式
├── tools/             # 工具模組
│   ├── contracts.py   # 合約搜尋
│   ├── market_data.py # 市場資料
│   ├── orders.py      # 訂單操作
│   ├── positions.py   # 持倉查詢
│   └── terms.py       # 服務條款
└── utils/             # 工具程式
    ├── auth.py        # 身份驗證管理
    ├── formatters.py  # 資料格式化
    └── shioaji_wrapper.py # Shioaji 包裝器

Avisos Importantes

⚠️ API de negociação real

  • Este servidor MCP conecta-se à API real da Yuanta Securities
  • Todas as operações de negociação executam ordens reais
  • Certifique-se de entender os riscos antes de negociar
  • Recomenda-se testar primeiro com valores pequenos
  • Este software é fornecido "no estado em que se encontra", sem garantias de qualquer tipo
  • Os usuários são responsáveis por suas próprias decisões de negociação e conformidade regulatória

⚠️ Compatibilidade

  • Python 3.10-3.12
  • Recomenda-se executar em ambiente Linux ou Docker
  • Usuários de macOS devem usar Docker

Solução de Problemas

Teste de configuração do Docker

Fornecemos um script para testar se sua configuração do Docker é compatível com o servidor MCP Shioaji:

# 使腳本可執行
chmod +x scripts/test_docker_setup.sh

# 執行測試腳本
./scripts/test_docker_setup.sh

Este script verifica a instalação do Docker, status do daemon, permissões, suporte de plataforma e funcionalidade básica.

Problemas de dependências no macOS

# 使用 Docker 解決
docker run --platform=linux/amd64 ...

Problemas de conexão com a API

# 檢查環境變數
echo $SHIOAJI_API_KEY
echo $SHIOAJI_SECRET_KEY

# 檢查 API 憑證是否有效
docker run --rm -i --platform=linux/amd64 \
  -e SHIOAJI_API_KEY=your_key \
  -e SHIOAJI_SECRET_KEY=your_secret \
  shioaji-mcp python -c "from shioaji_mcp.utils.auth import auth_manager; print(auth_manager.is_connected())"

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE.

Contribuições

Aceitamos contribuições para melhorar o servidor MCP Shioaji! Consulte CONTRIBUTING.md para obter diretrizes detalhadas sobre como contribuir com este projeto.

  1. Faça um fork deste projeto
  2. Crie um branch de funcionalidade
  3. Faça alterações e adicione testes
  4. Execute verificações de código e testes
  5. Envie um Pull Request