deribit-mcp

Conecta Deribit a tu asistente de IA. Compatible con Claude Code, Codex y cualquier cliente MCP, se integra con un solo comando para que el asistente pueda consultar el mercado, ver la cuenta y gestionar órdenes.

claude mcp add deribit -- npx -y deribit-mcp

Nada más instalarlo puedes preguntar: "¿Cómo está la cadena de opciones de BTC ahora?", "Mira la volatilidad implícita de las opciones call que vencen en marzo", "¿Cuánto margen disponible tengo en mi cuenta?"

Dos valores de seguridad por defecto: por defecto se conecta a la red de pruebas y por defecto las operaciones están desactivadas. Para hacer una orden real hay que activar ambas explícitamente.

Instalación

Claude Code

Solo para consultar el mercado, sin necesidad de configuración:

claude mcp add deribit -- npx -y deribit-mcp

Para consultar cuenta y órdenes, añade las credenciales API y cambia a la red principal:

claude mcp add deribit \
  --env DERIBIT_ENV=prod \
  --env DERIBIT_CLIENT_ID=你的_client_id \
  --env DERIBIT_CLIENT_SECRET=你的_client_secret \
  -- npx -y deribit-mcp

Codex

Edita ~/.codex/config.toml (o .codex/config.toml del proyecto):

[mcp_servers.deribit]
command = "npx"
args = ["-y", "deribit-mcp"]

[mcp_servers.deribit.env]
DERIBIT_ENV = "prod"
DERIBIT_CLIENT_ID = "你的_client_id"
DERIBIT_CLIENT_SECRET = "你的_client_secret"

Otros clientes MCP

Cualquier cliente compatible con stdio puede usarlo. El comando es npx -y deribit-mcp y la configuración se pasa mediante variables de entorno.

Ejecutar desde el código fuente (opcional)

Si quieres fijar una versión concreta o has modificado el código, puedes apuntar directamente al código fuente sin necesidad de reconstruir cada vez que cambies algo:

git clone https://github.com/freeeverett/deribit-mcp.git
cd deribit-mcp && npm install

[mcp_servers.deribit]
command = "npx"
args = ["tsx", "/绝对路径/deribit-mcp/src/index.ts"]

El coste es un arranque aproximadamente el doble de lento (unos 160 ms frente a 77 ms) y requiere tener las dependencias instaladas localmente. Para el uso diario se recomienda seguir usando npx -y deribit-mcp.

Obtener credenciales API

Crea una key en Configuración de la cuenta Deribit → API.

Se recomienda aplicar el principio de mínimo privilegio: si solo quieres que el asistente te ayude a analizar, con trade:read es suficiente. Así, aunque actives el interruptor de trading por error, no podrá enviar órdenes.

Related MCP server: Crypto Options Desk MCP

Opciones de configuración

La red de pruebas es independiente: la cuenta y las claves API de test.deribit.com no son compatibles en absoluto con la red principal. Hay que registrarse por separado en test.deribit.com. En la red de pruebas se pueden obtener monedas de prueba gratis, ideal para probar el flujo antes de pasar a la red principal.

Pruebas de integración completas en la red de pruebas

Crea un archivo .env.test (ignorado por git) en la raíz del proyecto con solo las credenciales API de la red de pruebas:

DERIBIT_CLIENT_ID=你的测试网_client_id
DERIBIT_CLIENT_SECRET=你的测试网_client_secret

Después ejecuta:

npm run test:all

Esta entrada lee de forma nativa .env.test y fuerza la conexión a la red de pruebas (no usará la red principal ni los endpoints personalizados del archivo). Ejecuta los 39 herramientas a través de un cliente MCP stdio real y requiere que la key tenga trade:read_write: crea, modifica y cancela órdenes limitadas con etiquetas de prueba únicas, abre y cierra brevemente posiciones de mercado y crea un combo de prueba. Al salir, el script cancela las órdenes pendientes según la etiqueta; si la limpieza falla, el comando termina con error. El npm run smoke existente sigue siendo una regresión rápida de interfaces públicas que no requiere credenciales.

Sobre la función de trading

Las herramientas relacionadas con el envío de órdenes no están habilitadas por defecto — si no rellenas DERIBIT_ENABLE_TRADING=true, tu asistente ni siquiera verá estas herramientas, por lo que no hay riesgo de activarlas por accidente.

Una vez activadas, estarán disponibles: enviar órdenes, modificar órdenes, cancelar órdenes, cerrar posiciones y crear contratos de combo.

Ten muy en cuenta:

• Estas operaciones generarán operaciones reales en tu cuenta real, el dinero es real

• Se recomienda practicar primero en la red de pruebas antes de considerar la red principal

• En la red principal con trading activado, el servicio mostrará una advertencia explícita al arrancar y el asistente recibirá la instrucción de "confirmar con el usuario antes de ejecutar"

• Pero la puerta final eres tú: cuando aparezca cualquier solicitud de orden, revísala bien antes de dar tu consentimiento

Si solo quieres que el asistente haga análisis y no quieres que toque las órdenes, no actives este interruptor — las consultas de mercado y de cuenta no se ven afectadas en absoluto.

Qué puede hacer

39 herramientas en total.

Mercado (18, sin necesidad de credenciales)

Lista de contratos y monedas, especificaciones de contratos, fechas de vencimiento, cadena de opciones (interés abierto / volatilidad implícita / precios de compra y venta), cotizaciones en tiempo real y profundidad del libro de órdenes, Griegas de opciones, velas históricas, historial de precios de marca, precio del índice actual e histórico, volatilidad realizada histórica, índice de volatilidad DVOL, tasa de financiación de perpetuos, operaciones de todo el mercado, volumen del exchange, APR de tokens con rendimiento, precio de liquidación, registros de liquidación y quiebras, contratos de combo, estado de la plataforma, anuncios del exchange.

Cuenta y órdenes (16, requieren credenciales)

Patrimonio de la cuenta y margen, resumen de todas las monedas y bloqueo de cuenta, detalle de posiciones, lista de subcuentas, simulación de margen de cartera, movimientos de fondos, registros de liquidación y entrega, movimientos de depósitos/retiros/transferencias, órdenes abiertas actuales, estado de órdenes, historial de órdenes, historial de órdenes activadas, detalle de operaciones, operaciones de una orden concreta, estimación de margen para enviar órdenes.

Trading (5, requieren credenciales y activación explícita)

Enviar órdenes (límite / mercado / stop / take profit / trailing stop / iceberg / precios avanzados de opciones), modificar órdenes, cancelar órdenes, cerrar posiciones, crear contratos de combo de múltiples patas.

La correspondencia completa entre herramientas e interfaces está en docs/API-COVERAGE.md.

Cómo leer el número de versión

El número de versión tiene la forma 2.20260721.0:

• 2 — Versión principal de la API de Deribit (v2)

• 20260721 — Fecha de publicación de la documentación oficial de Deribit a la que se alinea (2026-07-21)

• 0 — Número de revisión dentro de esa versión de documentación

Es decir, con solo mirar la parte central sabes a qué fecha de la documentación de Deribit corresponde esta versión. Cuando Deribit actualice sus interfaces, este proyecto actualizará esa parte central a la nueva fecha.

Preguntas frecuentes

¿El asistente dice que no encuentra las herramientas de Deribit? Revisa los registros MCP del cliente. Al arrancar, el servicio imprime en stderr el entorno actual, el estado de las credenciales y el número de herramientas registradas. De un vistazo puedes ver si la configuración no se aplicó o si hay otro problema.

¿Solo se ven las herramientas de mercado y las de cuenta han desaparecido? Significa que las credenciales no se leyeron. Confirma que DERIBIT_CLIENT_ID y DERIBIT_CLIENT_SECRET están ambas configuradas — si solo se configura una, el servicio fallará al arrancar e indicará cuál falta.

¿No se ven las herramientas de envío de órdenes? Se necesita DERIBIT_ENABLE_TRADING=true y que las credenciales estén configuradas. Este es el comportamiento predeterminado intencionado.

¿Error invalid_credentials? La key o el secret son incorrectos, o has puesto una key de la red de pruebas conectándote a la red principal (o viceversa). Las cuentas de ambos lados no son compatibles.

¿Error de scope insuficiente? La clave API no tiene el permiso trade:read_write. El servicio dará el error antes de enviar la orden, para que no pienses que la orden ya se ha enviado. Ve al panel de Deribit a añadir permisos a la key o desactiva el interruptor de trading.

¿He cambiado la configuración y no surte efecto? El servicio MCP se inicia cuando arranca el cliente. Después de cambiar las variables de entorno hay que reiniciar el cliente.

Licencia

MIT