deribit-mcp

Deribit을 AI 어시스턴트에 연결하세요. Claude Code, Codex 등 모든 MCP 클라이언트를 지원하며, 한 줄 명령으로 연결하여 어시스턴트가 시세 조회, 계정 확인, 주문 관리를 할 수 있게 해줍니다.

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

설치만 하면 이렇게 물어볼 수 있습니다: "BTC 옵션 체인 지금 어떤데?", "3월 만기 콜옵션 내재변동성 좀 봐줘", "내 계정에 사용 가능한 증거금 얼마나 남았어?"

두 가지 안전 기본값: 기본적으로 테스트넷에 연결되고, 기본적으로 거래가 비활성화됩니다. 실제 주문을 하려면 두 곳을 모두 명시적으로 켜야 합니다.

설치

Claude Code

시세 조회만 하려면 별도 설정이 필요 없습니다:

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

계정과 주문을 조회하려면 API 자격 증명을 추가하고 메인넷으로 전환하세요:

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

~/.codex/config.toml(또는 프로젝트의 .codex/config.toml)을 편집하세요:

[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"

기타 MCP 클라이언트

stdio를 지원하는 모든 클라이언트에서 사용할 수 있으며, 명령은 npx -y deribit-mcp이고 환경 변수로 설정을 전달합니다.

소스에서 실행(선택 사항)

특정 버전에 고정하고 싶거나 코드를 직접 수정한 경우, 소스를 직접 가리킬 수 있으며 매번 수정 후 다시 빌드할 필요가 없습니다:

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"]

단점은 시작 속도가 약 2배 느리고(약 160ms vs 77ms), 로컬에 의존성이 설치되어 있어야 한다는 점입니다. 일상적인 사용에는 여전히 npx -y deribit-mcp를 권장합니다.

API 자격 증명 얻기

Deribit 계정 설정 → API에서 key를 생성하세요.

최소 권한 원칙을 권장합니다: 어시스턴트에게 분석만 시키려면 trade:read면 충분합니다. 이렇게 하면 실수로 거래 스위치를 켜도 주문을 낼 수 없습니다.

Related MCP server: Crypto Options Desk MCP

설정 항목

테스트넷은 독립적입니다: test.deribit.com의 계정과 API key는 메인넷과 완전히 호환되지 않으므로, test.deribit.com에서 별도로 가입해야 합니다. 테스트넷에서 테스트 코인을 무료로 받을 수 있으며, 먼저 흐름을 익힌 후 메인넷으로 전환하기에 적합합니다.

전체 테스트넷 통합 테스트

프로젝트 루트에 git에서 무시되는 .env.test를 만들고 테스트넷 API 자격 증명만 넣으세요:

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

그런 다음 실행:

npm run test:all

이 진입점은 .env.test를 기본적으로 읽고 테스트넷 연결을 강제합니다(파일의 메인넷 또는 사용자 지정 엔드포인트 설정은 적용되지 않습니다). 실제 stdio MCP 클라이언트를 통해 전체 39개 도구를 실행하며, key에 trade:read_write 권한이 필요합니다: 고유 테스트 태그가 있는 지정가 주문을 생성·수정·취소하고, 잠시 시장가로 포지션을 열고 청산하며, 테스트 콤보 계약을 생성합니다. 스크립트 종료 시 해당 태그로 주문 취소를 보장합니다; 정리 실패 시 명령은 실패로 종료됩니다. 기존 npm run smoke는 자격 증명이 필요 없는 빠른 공개 인터페이스 회귀 테스트입니다.

거래 기능에 대하여

주문 관련 도구는 기본적으로 비활성화되어 있습니다 — DERIBIT_ENABLE_TRADING=true를 설정하지 않으면 어시스턴트가 이러한 도구를 아예 볼 수 없으므로 실수로 건드릴 일도 없습니다.

활성화하면 사용 가능: 주문, 주문 변경, 주문 취소, 청산, 콤보 계약 생성.

반드시 알아두세요:

• 이러한 작업은 실제 계정에서 실제 체결을 발생시키며, 돈은 진짜입니다

• 먼저 테스트넷에서 흐름을 충분히 익힌 후 메인넷을 고려하세요

• 메인넷 + 거래 활성화 시, 서비스 시작 시 명시적 경고가 출력되고 어시스턴트도 "실행 전 반드시 사용자 확인 필요" 지시를 받습니다

• 하지만 최종 관문은 당신 자신입니다: 주문 요청이 나타나면 먼저 잘 확인한 후 동의를 누르세요

어시스턴트에게 분석만 시키고 주문을 건드리게 하고 싶지 않다면 이 스위치를 켜지 마세요 — 시세와 계정 조회는 전혀 영향을 받지 않습니다.

할 수 있는 것

총 39개 도구.

시세(18개, 자격 증명 불필요)

계약 및 코인 목록, 계약 사양, 만기일, 옵션 체인(미결제약정 / 내재변동성 / 매수·매도 호가), 실시간 시세 및 호가창 깊이, 옵션 Greeks, 과거 K-라인, 마크 가격 이력, 지수 현물가 및 이력, 과거 실현변동성, DVOL 변동성 지수, 무기한 펀딩 비율, 전체 시장 체결, 거래소 거래량, 이자 발생 토큰 APR, 결제가, 정산 및 청산 기록, 콤보 계약, 플랫폼 상태, 거래소 공지.

계정 및 주문(16개, 자격 증명 필요)

계정 자산 및 증거금, 전체 코인 개요 및 계정 잠금, 포지션 상세, 하위 계정 목록, 포트폴리오 마진 시뮬레이션, 자금 내역, 정산 및 결제 기록, 입출금 이체 내역, 현재 미체결 주문, 주문 상태, 과거 주문, 트리거 주문 이력, 체결 상세, 단일 주문 체결, 주문 증거금 견적.

거래(5개, 자격 증명 필요 및 명시적 활성화)

주문(지정가 / 시장가 / 손절 / 이익실현 / 트레일링 스톱 / 아이스버그 / 옵션 고급 가격), 주문 변경, 주문 취소, 청산, 다리 콤보 계약 생성.

전체 도구와 API 대응 관계는 docs/API-COVERAGE.md를 참조하세요.

버전 번호 보는 법

버전 번호 형식은 2.20260721.0입니다:

• 2 — Deribit API 메이저 버전(v2)

• 20260721 — 정렬된 Deribit 공식 문서 게시일(2026-07-21)

• 0 — 해당 문서 버전에서의 몇 번째 수정인지

즉, 가운데 부분만 보면 이 버전이 언제의 Deribit 문서를 따르는지 알 수 있습니다. Deribit이 API를 업데이트하면 이 프로젝트도 가운데 부분을 새 날짜로 갱신합니다.

자주 묻는 질문

어시스턴트가 Deribit 도구를 찾을 수 없다고 하나요? 클라이언트의 MCP 로그를 확인하세요. 서비스 시작 시 현재 환경, 자격 증명 상태, 등록된 도구 수를 stderr로 출력하므로 설정이 적용되지 않았는지 다른 문제인지 한눈에 알 수 있습니다.

시세 도구만 보이고 계정 도구가 모두 사라졌나요? 자격 증명이 읽히지 않았다는 뜻입니다. DERIBIT_CLIENT_ID와 DERIBIT_CLIENT_SECRET 둘 다 설정했는지 확인하세요 — 하나만 설정하면 서비스가 시작 실패하며 무엇이 누락되었는지 알려줍니다.

주문 도구가 안 보이나요? DERIBIT_ENABLE_TRADING=true와 자격 증명 설정이 필요합니다. 이는 의도된 기본 동작입니다.

invalid_credentials 오류가 발생하나요? key 또는 secret이 잘못되었거나, 테스트넷 key로 메인넷에 연결했거나 그 반대입니다. 양쪽 계정은 호환되지 않습니다.

scope 부족 오류가 발생하나요? API key에 trade:read_write 권한이 없습니다. 서비스는 주문 전에 오류를 보고하므로 주문이 이미 나간 것으로 착각하지 않게 해줍니다. Deribit 백엔드에서 key에 권한을 추가하거나 거래 스위치를 끄세요.

설정을 변경했는데 적용되지 않나요? MCP 서비스는 클라이언트 시작 시 실행되므로, 환경 변수를 변경한 후 클라이언트를 재시작해야 합니다.

License

MIT