Servidor MCP de Luno

Un servidor de Protocolo de Contexto de Modelo (MCP) para la API de intercambio de criptomonedas Luno. Este servidor proporciona una interfaz estandarizada para que los modelos y aplicaciones de IA interactúen con la API de Luno para el comercio de criptomonedas.

 _                        __  __  ____ ____   
| |    _   _ _ __   ___  |  \/  |/ ___|  _ \  
| |   | | | | '_ \ / _ \ | |\/| | |   | |_) | 
| |___| |_| | | | | (_) || |  | | |___|  __/  
|_____|\__,_|_| |_|\___/ |_|  |_|\____|_|     

Características

Información sobre el precio de las criptomonedas en tiempo real a través de la API de Luno
Descripción general del mercado para todos los pares comerciales
Consultas de saldo de cuenta
Gestión de pedidos (realizar, cancelar, estado)
Recuperación del historial de transacciones
Información sobre tarifas
Interfaz JSON-RPC 2.0 estandarizada
Integración sencilla con aplicaciones de IA

Prerrequisitos

Python 3.8+ (se recomienda Python 3.9+)
uv para la gestión de paquetes
Cuenta Luno con claves API (para funcionalidad completa)

Instalación

Clonar este repositorio

git clone https://github.com/amanasmuei/mcp-luno.git
cd mcp-luno

Crea un entorno virtual usando uv

uv venv
source .venv/bin/activate  # On macOS/Linux
# On Windows use: .venv\Scripts\activate

Instalar dependencias

uv pip install -r requirements.txt

Configure sus credenciales de API de Luno (elija un método):

Soporte de Docker

Puede ejecutar el servidor MCP usando Docker para una implementación más sencilla y un entorno consistente en diferentes plataformas.

Uso de Docker Compose (recomendado)

Copie el archivo de entorno de ejemplo y configure sus credenciales:

cp .env.example .env
# Edit .env file with your Luno API credentials

Iniciar el servidor:

docker compose up -d

El servidor estará disponible en ws://localhost:8765 en modo WebSocket.

Ver registros:

docker compose logs -f

Detener el servidor:

docker compose down

Usando Docker directamente

Construye la imagen:

docker build -t mcp-luno .

Ejecute el contenedor:

docker run -d \
  -p 8765:8765 \
  -e LUNO_API_KEY=your_api_key_here \
  -e LUNO_API_SECRET=your_api_secret_here \
  -e MCP_TRANSPORT=websocket \
  -e MCP_HOST=0.0.0.0 \
  -v ./certs:/app/certs \
  --name mcp-luno \
  mcp-luno

Uso con asistentes de IA

Después de iniciar el contenedor Docker, puede conectar varios asistentes de IA para usar el servidor Luno MCP:

Cursor

Agregue lo siguiente a su configuración de Cursor:

{
  "mcp_servers": {
    "luno": {
      "type": "websocket",
      "url": "ws://localhost:8765"
    }
  }
}

Escritorio de Claude

En la configuración de Claude Desktop, tienes dos opciones para configurar el servidor MCP:

Opción 1: Usar Docker (recomendado)

{
  "mcpServers": {
    "luno": {
      "command": "docker",
      "args": ["compose", "up"],
      "cwd": "/path/to/mcp-luno",
      "transport": "websocket",
      "url": "ws://localhost:8765",
      "env": {
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

Esta configuración inicia el servidor en un contenedor Docker y se conecta a través de WebSocket.

Opción 2: Usar la ejecución directa de Python

{
  "mcpServers": {
    "luno": {
      "command": "python",
      "args": ["-m", "src.main", "--transport", "stdio"],
      "cwd": "/path/to/mcp-luno",
      "transport": "stdio",
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here"
      }
    }
  }
}

Esta configuración ejecuta el servidor Python directamente utilizando el transporte STDIO.

Nota: Reemplace /path/to/mcp-luno con la ruta real donde clonó el repositorio.

Cline

Agregue lo siguiente a su archivo de configuración de Cline:

{
  "mcp": {
    "servers": {
      "luno": {
        "transport": "websocket",
        "url": "ws://localhost:8765"
      }
    }
  }
}

Compatibilidad con SSL con Docker

Para utilizar SSL con el contenedor Docker:

Genere certificados utilizando el script proporcionado:

./generate_certificates.sh

Monte el directorio de certificados al ejecutar el contenedor:

docker run -d \
  -p 8765:8765 \
  -e LUNO_API_KEY=your_api_key_here \
  -e LUNO_API_SECRET=your_api_secret_here \
  -e MCP_TRANSPORT=websocket \
  -e MCP_HOST=0.0.0.0 \
  -v ./certs:/app/certs \
  --name mcp-luno \
  mcp-luno

Instalación manual

Opción A : Usar el archivo .env

cp .env.example .env

Luego edite el archivo .env para agregar sus credenciales de API de Luno:

LUNO_API_KEY=your_api_key_here
LUNO_API_SECRET=your_api_secret_here

Opción B : Uso de la configuración MCP de VS Code

Edite el archivo .vscode/mcp.json y agregue sus credenciales a la sección env :

"env": {
  "PYTHONPATH": "${workspaceFolder}",
  "LUNO_API_KEY": "your_api_key_here",
  "LUNO_API_SECRET": "your_api_secret_here",
  "LOG_LEVEL": "INFO"
}

Nota : Sin credenciales de API válidas, solo estarán disponibles los endpoints públicos. Recomendación : Por seguridad, priorice las variables de entorno al compartir código.

Ejecución del servidor

Puede ejecutar el servidor MCP en dos modos de transporte diferentes:

Transporte STDIO (predeterminado, cliente único)

Este es el modo predeterminado, que admite una única conexión de cliente a través de entrada/salida estándar:

python -m src.main --transport stdio

Transporte de WebSockets (múltiples clientes)

Para admitir varias conexiones de cliente simultáneamente, ejecute el servidor en modo WebSocket:

python -m src.main --transport websocket [--host HOST] [--port PORT]

El servidor WebSocket se iniciará en ws://localhost:8765 de forma predeterminada.

Prueba del servidor WebSocket

Puede probar el servidor WebSocket utilizando el cliente de prueba incluido:

python test_websocket_client.py

Esto ayuda a verificar que el servidor esté manejando correctamente las conexiones WebSocket y respondiendo a las solicitudes.

Opciones de línea de comandos

--transport {stdio,websocket} : Mecanismo de transporte a utilizar (predeterminado: stdio)
--host HOST : Host al que vincularse cuando se utiliza el transporte WebSocket (predeterminado: localhost)
--port PORT : Puerto al que vincular cuando se utiliza el transporte WebSocket (predeterminado: 8765)

Variables de entorno

También puedes configurar el transporte utilizando variables de entorno:

MCP_TRANSPORT : Mecanismo de transporte ("stdio" o "websocket")
MCP_HOST : Host al que vincular para el transporte WebSocket
MCP_PORT : Puerto al que vincular para el transporte de WebSocket

Pruebas con el cliente estándar

Para probar el transporte STDIO, utilice el cliente de prueba incluido:

python test_client.py

Integración del protocolo MCP

Este servidor implementa el Protocolo de Contexto de Modelo (MCP), que permite a los modelos de IA interactuar con él mediante mensajes JSON-RPC 2.0 estandarizados. El servidor opera sobre STDIO de forma predeterminada, lo que facilita la integración con extensiones de VS Code y otros clientes compatibles con MCP.

Integración de VS Code

El archivo .vscode/mcp.json configura el servidor para su uso con VS Code. Se ofrecen dos configuraciones de servidor:

luno-mcp-server-stdio : utiliza el transporte STDIO (comportamiento MCP predeterminado)
luno-mcp-server-websocket : utiliza el transporte WebSocket para la compatibilidad con múltiples clientes

Configuración de VS Code

Para utilizar el transporte WebSocket con VS Code, el archivo mcp.json incluye una configuración de tipo de proceso:

"luno-mcp-server-websocket": {
  "type": "process",
  "command": "python",
  "args": ["-m", "src.main", "--transport", "websocket"],
  "env": {
    // environment variables
  }
}

Al utilizar el transporte WebSocket, VS Code iniciará el servidor como un proceso en segundo plano en lugar de comunicarse a través de STDIO.

Configuración del servidor MCP en VS Code

Puede configurar el servidor directamente desde el archivo .vscode/mcp.json :

{
  "servers": {
    "luno-mcp-server": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "src.main"],
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "LUNO_API_KEY": "your_api_key_here",
        "LUNO_API_SECRET": "your_api_secret_here",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Esta configuración será utilizada por las extensiones de VS Code que admiten el protocolo MCP, lo que facilita la integración con modelos de IA y otras herramientas.

Métodos disponibles

Método	Descripción	Se requiere autenticación
`describe_capabilities`	Devolver información sobre las capacidades del servidor	No
`get_crypto_price`	Obtenga el precio actual de un par comercial específico	No
`get_market_overview`	Obtenga una descripción general de todos los mercados disponibles	No
`get_account_balance`	Obtenga el saldo de todas las cuentas	Sí
`place_order`	Realizar un nuevo pedido	Sí
`cancel_order`	Cancelar un pedido existente	Sí
`get_order_status`	Obtener el estado de un pedido	Sí
`get_transaction_history`	Obtener el historial de transacciones de una cuenta	Sí
`get_fees`	Obtenga información sobre las tarifas para un par comercial	Sí

Solicitudes de ejemplo

Obtener capacidades del servidor:

{
  "jsonrpc": "2.0",
  "method": "describe_capabilities",
  "params": {},
  "id": 1
}

Obtenga el precio de Bitcoin-ZAR:

{
  "jsonrpc": "2.0",
  "method": "get_crypto_price",
  "params": {"pair": "XBTZAR"},
  "id": 2
}

Desarrollo

Estructura del proyecto

├── .env                 # Environment variables (API credentials)
├── .gitignore           # Git ignore configuration
├── .vscode/             # VS Code specific settings
│   └── mcp.json         # MCP configuration for VS Code
├── src/                 # Source code
│   ├── main.py          # Entry point
│   └── luno_mcp_server/ # MCP server implementation
│       ├── luno_client.py # Luno API client
│       └── server.py    # MCP server core
├── tests/               # Test suite
├── test_client.py       # Simple test client for the MCP server
├── requirements.txt     # Project dependencies
└── setup.py             # Package setup

Ejecución de pruebas

python -m pytest tests/

Añadiendo nuevas funciones

Para agregar nuevas capacidades de API de Luno:

Amplíe la clase LunoClient en src/luno_mcp_server/luno_client.py con nuevos métodos de API
Agregue los métodos correspondientes en la clase LunoMCPServer en src/luno_mcp_server/server.py
Actualice la lista MCP_METHODS en server.py y registre sus métodos en la función _register_methods
Agregar pruebas en el directorio tests/

Arquitectura

El servidor MCP utiliza una arquitectura simple:

JSON-RPC 2.0 para la comunicación
Entrada/salida estándar (STDIO) para transporte
Cliente API de Luno para operaciones con criptomonedas

Solución de problemas

Problemas comunes

Errores de autenticación de API : asegúrese de que sus claves de API de Luno estén configuradas correctamente en el archivo .env o en .vscode/mcp.json
Errores de importación : Asegúrese de haber activado el entorno virtual
Limitación de velocidad : la API de Luno tiene límites de velocidad: implemente la lógica de reintento para uso en producción

Prioridad de configuración

Al iniciar el servidor, los valores de configuración se cargan en este orden de prioridad:

Variables de entorno pasadas a través de la configuración de MCP (máxima prioridad)
Valores en el archivo .env
Valores predeterminados en el código (prioridad más baja)

Esto significa que puede establecer valores en la configuración de MCP para anular cualquier valor existente en su archivo .env .

Soporte multicliente

Este servidor MCP admite varias conexiones de cliente simultáneamente mediante WebSockets. Para obtener información detallada, consulte MULTI_CLIENT_SUPPORT.md .

Opciones de transporte

El servidor admite dos mecanismos de transporte:

STDIO (predeterminado): entrada/salida estándar (cliente único), utilizada por VS Code MCP
WebSockets : Transporte de red: múltiples clientes con funciones de seguridad

Ejecución con transporte WebSockets

Uso básico:

python -m src.main --transport websocket --host localhost --port 8765

Con opciones de seguridad:

python -m src.main --transport websocket --host localhost --port 8765 \
  --max-connections 50 --max-message-size 1048576 --rate-limit 100

Con cifrado SSL/TLS:

# First generate certificates
./generate_certificates.sh

# Then run with SSL support
python -m src.main --transport websocket --ssl-cert ./certs/server.crt --ssl-key ./certs/server.key

Herramientas de cliente WebSocket

El repositorio incluye dos herramientas cliente:

test_websocket_client.py : Cliente de prueba simple
python test_websocket_client.py
improved_websocket_client.py : Cliente avanzado con simulación multicliente
# Single client mode python enhanced_websocket_client.py --mode single # Multi-client simulation (3 clients) python enhanced_websocket_client.py --mode multi --clients 3

Licencia

Licencia MIT

Por la presente se concede permiso, sin cargo, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados.

Integrations