MCP

MCP란?

MCP(Model Context Protocol)는 AI 클라이언트에 외부 도구를 연결하는 표준 방식입니다. Claude Desktop, Cursor, VS Code 같은 클라이언트에 빗썸 MCP를 등록하면 시세 조회, 잔고 확인, 주문 같은 작업을 자연어로 처리할 수 있습니다.

클라이언트 설정 파일에 항목만 추가하면 npx로 MCP 서버가 사용자 로컬에서 자동 실행됩니다.

클라이언트 등록

AI 에이전트로 설정하거나 직접 설정할 수 있습니다. 이미 사용 중인 MCP 클라이언트(Claude Code, Cursor 등)가 에이전트 기능을 지원한다면, 아래 AI 에이전트로 설정이 가장 빠릅니다.

AI 에이전트로 설정

에이전트에 다음 프롬프트를 입력하세요.

`https://github.com/bithumb-official/bithumb-ai-trade-kit/blob/main/setup-mcp.md`을 읽고, 빗썸 MCP를 설치·설정해줘

에이전트가 페이지를 읽고 Node.js 점검, 클라이언트 설정 파일에 MCP 항목 추가, 시세 도구로 연결 확인까지 순서대로 수행합니다. 인증이 필요한 도구를 사용하려면 인증 설정에서 API Key를 등록한 뒤 정상 동작 확인으로 이동하세요. 에이전트가 처리에 실패하면 아래 설정 파일에 직접 추가하기를 따르세요.

설정 파일에 직접 추가하기

Node.js 18 이상이 필요합니다. node -v로 확인하고, 없다면 nodejs.org에서 설치하세요. 설정 파일의 ${...} 참조가 동작하려면 인증 설정에서 API Key 환경 변수를 먼저 등록해 두세요.

클라이언트마다 설정 파일 위치와 형식이 다릅니다. 사용하는 클라이언트 탭을 선택해 설정 파일에 아래 내용을 추가하세요.

{
  "mcpServers": {
    "bithumb": {
      "command": "npx",
      "args": ["-y", "@bithumb-official/bithumb-mcp", "--modules", "all"],
      "env": {
        "BITHUMB_ACCESS_KEY": "${BITHUMB_ACCESS_KEY}",
        "BITHUMB_SECRET_KEY": "${BITHUMB_SECRET_KEY}"
      }
    }
  }
}

설정을 저장한 뒤 클라이언트를 다시 시작하면 도구 목록에 빗썸 MCP 도구가 표시됩니다.

인증 설정

시세 조회 도구는 인증 없이 사용할 수 있습니다. 잔고·주문·입출금 도구는 API Key가 필요합니다. 빗썸 API 관리 페이지에서 발급하세요.

export BITHUMB_ACCESS_KEY="발급받은_액세스_키"
export BITHUMB_SECRET_KEY="발급받은_시크릿_키"

MCP 서버는 환경 변수만 사용합니다. CLI와 달리 ~/.bithumb/config.toml의 프로필은 읽지 않으며, --profile 옵션도 지원하지 않습니다. AI 클라이언트와 함께 실행되므로 환경 변수는 ~/.zshrc 또는 ~/.bashrc에 등록해 두는 편이 편합니다.

Windows 환경 등 세부 설정은 CLI 페이지의 인증 설정을 참고하세요.

정상 동작 확인

설정을 마쳤다면 아래 순서대로 연결 상태를 확인해보세요.

도구 목록 확인

클라이언트의 도구 패널에 market_get_ticker, account_get_assets 같은 빗썸 도구가 보이면 정상적으로 연결된 상태입니다.

도구가 보이지 않는다면 아래 문제 해결 항목을 참고하세요.

인증 없이 동작 확인

아래처럼 자연어로 요청해봅니다.

• "KRW-BTC 현재가 알려줘"
• "활성화된 모듈 뭐 있어?"

전체 상태 확인

system_diagnose를 호출하면 현재 활성화된 모듈, 인증 상태, API 연결까지 자세히 확인할 수 있습니다.

인증 동작 확인

API Key까지 정상 설정됐다면 아래 요청도 확인해봅니다.

• "내 잔고 확인해줘"

사용 예시

MCP 도구는 자연어로 자유롭게 호출할 수 있습니다. 다음은 자주 쓰는 요청 패턴입니다.

자세한 도구 목록은 아래 기능 모듈을 참고하세요.

기능 모듈

MCP 서버는 다음 기능 모듈로 도구를 제공합니다. 활성화된 모듈에 속한 도구만 클라이언트의 도구 패널에 표시됩니다.

Market: 인증 불필요

공개 시세 데이터를 조회합니다.

Account

계좌 잔고, 주문 가능 정보, 지갑 상태, API Key 정보를 조회합니다.

Trade

주문 생성·취소·조회, 다건 주문을 처리합니다.

TWAP

TWAP(Time-Weighted Average Price) 알고리즘 분할 주문을 생성·조회·취소합니다.

Deposit

입금 주소 생성·조회, 입금 내역, 원화 입금을 처리합니다.

Withdraw

가상자산 및 원화 출금을 처리합니다.

⚠️

deposit_krw와 withdraw_krw는 빗썸의 2차 인증이 필요합니다. API Key에 해당 권한이 있는지 확인하세요.

System

설정 진단, 로컬 실행 로그 조회 같은 운영 정보를 제공합니다.

실행 옵션

옵션은 클라이언트 설정 파일의 args 배열에 추가해서 사용합니다.

{
  "command": "npx",
  "args": ["-y", "@bithumb-official/bithumb-mcp", "--modules", "market,account", "--read-only"]
}

모듈 단위 노출

// 시세 조회만 활성화
"args": ["-y", "@bithumb-official/bithumb-mcp", "--modules", "market"]

// 시세와 계좌 조회만 활성화
"args": ["-y", "@bithumb-official/bithumb-mcp", "--modules", "market,account"]

// 전체 활성화하되 쓰기 차단
"args": ["-y", "@bithumb-official/bithumb-mcp", "--modules", "all", "--read-only"]

문제 해결

상세 로깅

args에 --verbose와 --log-level debug를 추가하면 stderr로 요청 URL, 응답 코드, 도구 실행에 사용된 입력값도 함께 표시됩니다.

도구가 클라이언트에 보이지 않을 때

1. 설정 파일 저장 후 클라이언트를 완전히 재시작합니다.
2. system_diagnose 도구를 호출해 서버가 정상적으로 실행되는지 확인합니다.
3. CLI가 설치되어 있다면 bithumb system diagnose로 인증·네트워크 상태를 점검합니다.
4. 클라이언트 로그에서 MCP 서버 시작 오류를 확인합니다.

실행 로그

MCP 서버의 모든 도구 호출은 CLI와 동일한 실행 로그 파일(~/.bithumb/logs/trade-YYYY-MM-DD.log)에 기록됩니다. MCP에서는 system_get_audit_log 도구로 조회할 수 있고, 비활성화하려면 args에 --no-log를 추가하세요. 로그 구조, 필터링, CLI 조회 명령은 CLI 페이지의 실행 로그 섹션을 참고하세요.

환경 변수

MCP 서버는 CLI와 동일한 환경 변수를 사용합니다. 변수 목록과 기본값은 CLI 페이지의 환경 변수 섹션을 참고하세요.

더 알아보기