Shioaji MCP Server

Accede a la API de trading Shioaji para datos financieros y operaciones de trading, requiriendo una cuenta de SinoPac Securities.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Shioaji

Servidor de Protocolo de Contexto de Modelo (MCP) que proporciona las funciones de la API de negociación Shioaji de SinoPac Securities, accediendo a las funciones de negociación a través de herramientas estandarizadas.

Chino tradicional | English

Características

Autenticación y conexión

  • get_account_info - Obtener información de la cuenta y estado de conexión

Datos de mercado

  • search_contracts - Buscar contratos de negociación por palabra clave, bolsa o categoría
  • get_snapshots - Obtener instantáneas de mercado en tiempo real para un contrato específico
  • get_kbars - Obtener datos históricos de velas (K-line) para un contrato

Operaciones de negociación

  • place_order - Realizar órdenes de compra/venta con parámetros específicos (requiere permisos)
  • cancel_order - Cancelar una orden existente según su ID (requiere permisos)
  • list_orders - Listar todas las órdenes y sus estados
  • get_positions - Obtener posiciones actuales y ganancias/pérdidas (admite acciones, futuros o todas las cuentas)
  • get_account_balance - Obtener saldos de cuenta e información de margen (admite acciones, futuros o todas las cuentas)

⚠️ Seguridad de negociación: Las operaciones de negociación (place_order, cancel_order) están deshabilitadas por defecto. Configure SHIOAJI_TRADING_ENABLED=true para habilitar las funciones de negociación.

Términos de servicio y cumplimiento

  • check_terms_status - Verificar el estado de firma de los términos de servicio y la finalización de las pruebas de API
  • run_api_test - Ejecutar pruebas de API para el cumplimiento de los términos de servicio (pruebas de inicio de sesión y de órdenes)

Requisitos previos

  1. Cuenta de SinoPac Securities: Necesita una cuenta de SinoPac Securities
  2. Credenciales de API: Solicite y obtenga una API Key y una Secret Key
  3. Términos de servicio: Complete la firma de documentos y las pruebas de API (consulte docs/SERVICE_TERMS.md)

Para obtener información detallada sobre las imágenes de Docker que utilizan GitHub Container Registry, consulte docs/CONTAINER_REGISTRY.md.

Instalación y uso

Usar la imagen de Docker preconstruida (recomendado)

La forma más sencilla es usar la imagen de Docker preconstruida de GitHub Container Registry:

# 拉取最新穩定版映像
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

Etiquetas disponibles

  • latest - Última versión estable de la rama principal
  • vX.Y.Z (por ejemplo, v0.1.0) - Lanzamiento de versión específica
  • dev - Última versión de desarrollo (puede incluir funciones experimentales)

Se recomienda usar etiquetas de versión específicas en entornos de producción.

Construir la imagen de Docker localmente

Si prefiere construir la imagen 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

Configuración del cliente MCP

Agregue la siguiente configuración a su 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"
      ]
    }
  }
}

Permisos de negociación:

  • Configure SHIOAJI_TRADING_ENABLED=false (predeterminado) para modo de solo lectura
  • Configure SHIOAJI_TRADING_ENABLED=true para habilitar operaciones de negociación

Ejemplo de habilitación de negociación:

"-e", "SHIOAJI_TRADING_ENABLED=true"

Para desarrollo o pruebas, puede usar la etiqueta dev:

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

Ejemplo de cliente Python

Proporcionamos un ejemplo de cliente Python que demuestra cómo usar el servidor MCP de Shioaji programáticamente:

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

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

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

El ejemplo muestra:

  • Conectarse al servidor MCP de Shioaji
  • Obtener información de la cuenta
  • Buscar contratos
  • Obtener datos de mercado en tiempo real
  • Obtener datos históricos de velas (K-line)
  • Recuperar posiciones y saldos de cuenta

Consulte el código completo en examples/python_client.py.

Desarrollo 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

Guía de desarrollo

Configuración del entorno

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

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

Pruebas

# 執行測試
uv run pytest

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

Calidad del código

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

# 型別檢查
uv run mypy src/

Desarrollo con 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

Arquitectura

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 包裝器

Notas importantes

⚠️ API de negociación real

  • Este servidor MCP se conecta a la API real de SinoPac Securities
  • Todas las operaciones de negociación ejecutan órdenes reales
  • Asegúrese de comprender los riesgos antes de operar
  • Se recomienda probar primero con montos pequeños
  • Este software se proporciona "tal cual", sin garantías de ningún tipo
  • El usuario es responsable de sus propias decisiones de negociación y del cumplimiento normativo

⚠️ Compatibilidad

  • Python 3.10-3.12
  • Se recomienda ejecutar en un entorno Linux o en Docker
  • Los usuarios de macOS deben usar Docker

Solución de problemas

Prueba de configuración de Docker

Proporcionamos un script para probar si su configuración de Docker es compatible con el servidor MCP de Shioaji:

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

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

Este script verifica la instalación de Docker, el estado del daemon, los permisos, la compatibilidad de la plataforma y las funciones básicas.

Problemas de dependencias en macOS

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

Problemas de conexión de 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())"

Términos de licencia

Este proyecto está bajo la licencia MIT - consulte el archivo LICENSE.

Contribuciones

¡Damos la bienvenida a contribuciones para mejorar el servidor MCP de Shioaji! Consulte CONTRIBUTING.md para obtener una guía detallada sobre cómo contribuir a este proyecto.

  1. Haga un fork de este proyecto
  2. Cree una rama de características
  3. Realice cambios y agregue pruebas
  4. Ejecute comprobaciones de código y pruebas
  5. Envíe un Pull Request