---
updatedAt: 2026-07-09T08:19:12.000Z
agentTools:
  projectIndex: https://apidocs.bithumb.com/llms.txt
---

# MCP

MCP 클라이언트에서 빗썸 API 도구를 자연어로 호출합니다.

## 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](https://nodejs.org/ko/download)에서 설치하세요. 설정 파일의 `${...}` 참조가 동작하려면 [인증 설정](#인증-설정)에서 API Key 환경 변수를 먼저 등록해 두세요.

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

<Tabs>
  <Tab title="Claude Code">
    프로젝트 단위로 등록하려면 프로젝트 루트의 `.mcp.json`에 다음을 추가합니다. 모든 프로젝트에 적용하려면 `~/.claude.json`에 추가합니다.

    ```json
    {
      "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}"
          }
        }
      }
    }
    ```

    `env`의 `${...}` 는 이미 등록된 환경 변수 값을 참조합니다. API Key를 설정 파일에 직접 넣고 싶지 않다면 `~/.zshrc` 등에 먼저 등록한 뒤 사용하세요.
  </Tab>

  <Tab title="Codex">
    프로젝트 단위는 프로젝트 루트의 `.codex/config.toml`, 전역은 `~/.codex/config.toml`에 다음을 추가합니다.

    ```toml
    [mcp_servers.bithumb]
    command = "npx"
    args = ["-y", "@bithumb-official/bithumb-mcp", "--modules", "all"]
    env_vars = ["BITHUMB_ACCESS_KEY", "BITHUMB_SECRET_KEY"]
    ```

    Codex는 TOML 형식을 씁니다. `env_vars`에는 전달할 환경 변수 이름만 나열하고 값은 직접 적지 않습니다.
  </Tab>

  <Tab title="Cursor">
    `~/.cursor/mcp.json`에 다음을 추가합니다.

    ```json
    {
      "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}"
          }
        }
      }
    }
    ```

    `env`의 `${...}` 는 이미 등록된 환경 변수 값을 참조합니다. API Key를 설정 파일에 직접 넣고 싶지 않다면 `~/.zshrc` 등에 먼저 등록한 뒤 사용하세요.
  </Tab>

  <Tab title="VS Code">
    워크스페이스 단위로 등록하려면 프로젝트의 `.vscode/mcp.json`에 다음을 추가합니다. 사용자 프로필 전역으로 등록하려면 명령 팔레트(`⇧⌘P`)에서 `MCP: Open User Configuration`을 실행해 열리는 파일에 같은 내용을 추가합니다.

    ```json
    {
      "servers": {
        "bithumb": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@bithumb-official/bithumb-mcp", "--modules", "all"],
          "env": {
            "BITHUMB_ACCESS_KEY": "${BITHUMB_ACCESS_KEY}",
            "BITHUMB_SECRET_KEY": "${BITHUMB_SECRET_KEY}"
          }
        }
      }
    }
    ```

    `env`의 `${...}` 는 이미 등록된 환경 변수 값을 참조합니다. API Key를 설정 파일에 직접 넣고 싶지 않다면 `~/.zshrc` 등에 먼저 등록한 뒤 사용하세요.
  </Tab>

  <Tab title="Windsurf">
    `~/.codeium/windsurf/mcp_config.json`에 다음을 추가합니다.

    ```json
    {
      "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}"
          }
        }
      }
    }
    ```

    `env`의 `${...}` 는 이미 등록된 환경 변수 값을 참조합니다. API Key를 설정 파일에 직접 넣고 싶지 않다면 `~/.zshrc` 등에 먼저 등록한 뒤 사용하세요.
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop 설정 파일에 다음을 추가합니다.

    * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * Windows: `%APPDATA%\Claude\claude_desktop_config.json`

    ```json
    {
      "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}"
          }
        }
      }
    }
    ```

    `env`의 `${...}` 는 이미 등록된 환경 변수 값을 참조합니다. API Key를 설정 파일에 직접 넣고 싶지 않다면 환경 변수를 먼저 등록한 뒤 사용하세요.
  </Tab>
</Tabs>

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

## 인증 설정

시세 조회 도구는 인증 없이 사용할 수 있습니다. 잔고·주문·입출금 도구는 API Key가 필요합니다. 빗썸 [API 관리 페이지](https://www.bithumb.com/react/api-support/management-api)에서 발급하세요.

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

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

Windows 환경 등 세부 설정은 [CLI 페이지의 인증 설정](cli#인증-설정)을 참고하세요.

## 정상 동작 확인

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

### 도구 목록 확인

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

도구가 보이지 않는다면 아래 [문제 해결](#도구가-클라이언트에-보이지-않을-때) 항목을 참고하세요.

### 인증 없이 동작 확인

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

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

### 전체 상태 확인

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

### 인증 동작 확인

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

* "내 잔고 확인해줘"

## 사용 예시

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

<Columns layout="auto">
  <Column>
    ### 시세 조회

    공개 시세 데이터를 자연어로 조회합니다.

    * "BTC 현재가 알려줘"
    * "ETH 1시간봉 24개 보여줘"
    * "거래 가능한 코인 다 보여줘"
  </Column>

  <Column>
    ### 잔고·포트폴리오

    내 계정 상태를 조회합니다.

    * "내 잔고 보여줘"
    * "KRW만 따로 보여줘"
    * "API 키 만료일 확인해줘"
  </Column>
</Columns>

<Columns layout="auto">
  <Column>
    ### 주문

    주문 생성·조회·취소를 실행합니다.

    * "BTC 10만원어치 시장가로 사줘"
    * "내 미체결 주문 보여줘"
    * "방금 낸 주문 취소해줘"
  </Column>

  <Column>
    ### 입출금

    입출금 주소 조회와 실행을 처리합니다.

    * "BTC 입금 주소 알려줘"
    * "출금 수수료 얼마야?"
    * "최근 출금 내역 보여줘"
  </Column>
</Columns>

자세한 도구 목록은 아래 [기능 모듈](#기능-모듈)을 참고하세요.

## 기능 모듈

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

### Market: 인증 불필요

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

| 도구                           | 설명              |
| ---------------------------- | --------------- |
| `market_get_markets`         | 거래 가능 페어 목록 조회  |
| `market_get_ticker`          | 현재가 조회          |
| `market_get_orderbook`       | 호가창 조회          |
| `market_get_trades`          | 최근 체결 내역 조회     |
| `market_get_candles_minutes` | 분봉 캔들(OHLCV) 조회 |
| `market_get_candles_days`    | 일봉 캔들 조회        |
| `market_get_candles_weeks`   | 주봉 캔들 조회        |
| `market_get_candles_months`  | 월봉 캔들 조회        |
| `market_get_fee_inout`       | 입출금 수수료 조회      |
| `market_get_notices`         | 공지사항 목록 조회      |
| `market_get_warnings`        | 투자경보 페어 목록 조회   |

### Account

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

| 도구                          | 설명                          |
| --------------------------- | --------------------------- |
| `account_get_assets`        | 전체 계좌 잔고 조회                 |
| `account_get_api_keys`      | API Key 목록 및 만료일 조회         |
| `account_get_order_chance`  | 주문 가능 정보 조회(가용 잔고, 수수료, 한도) |
| `account_get_wallet_status` | 입출금 현황 조회(블록 상태, 가능 여부)     |

### Trade

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

| 도구                   | 설명                  |
| -------------------- | ------------------- |
| `trade_place_order`  | 주문 요청(지정가/시장가)      |
| `trade_cancel_order` | 주문 취소               |
| `trade_get_order`    | 개별 주문 상세 조회         |
| `trade_get_orders`   | 주문 리스트 조회           |
| `trade_batch_place`  | 다건 주문 일괄 생성(최대 20건) |
| `trade_batch_cancel` | 다건 주문 일괄 취소(최대 30건) |

### TWAP

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

| 도구                  | 설명            |
| ------------------- | ------------- |
| `twap_place_order`  | TWAP 주문 요청    |
| `twap_cancel_order` | TWAP 주문 취소    |
| `twap_get_orders`   | TWAP 주문 내역 조회 |

### Deposit

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

| 도구                         | 설명                  |
| -------------------------- | ------------------- |
| `deposit_get_list`         | 코인 입금 리스트 조회        |
| `deposit_get_list_krw`     | 원화 입금 리스트 조회        |
| `deposit_get`              | 개별 입금 조회            |
| `deposit_get_address`      | 특정 통화·네트워크 입금 주소 조회 |
| `deposit_get_addresses`    | 전체 입금 주소 조회         |
| `deposit_generate_address` | 입금 주소 생성 요청         |
| `deposit_krw`              | 원화 입금 요청(2차 인증 필요)  |

### Withdraw

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

| 도구                       | 설명                     |
| ------------------------ | ---------------------- |
| `withdraw_get_list`      | 코인 출금 리스트 조회           |
| `withdraw_get_list_krw`  | 원화 출금 리스트 조회           |
| `withdraw_get`           | 개별 출금 조회               |
| `withdraw_get_chance`    | 출금 가능 정보 조회(잔고·수수료·한도) |
| `withdraw_get_addresses` | 출금 허용 주소 리스트 조회        |
| `withdraw_coin`          | 가상자산 출금 요청             |
| `withdraw_cancel_coin`   | 가상자산 출금 취소             |
| `withdraw_krw`           | 원화 출금 요청(2차 인증 필요)     |

<Callout icon="fa-triangle-exclamation" theme="warning">
  `deposit_krw`와 `withdraw_krw`는 빗썸의 2차 인증이 필요합니다. API Key에 해당 권한이 있는지 확인하세요.
</Callout>

### System

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

| 도구                     | 설명                     |
| ---------------------- | ---------------------- |
| `system_diagnose`      | 설정 진단(API 연결·인증·모듈 상태) |
| `system_get_audit_log` | 로컬 실행 로그 조회            |

## 실행 옵션

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

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

| 옵션                    | 설명                                      | 기본값     |
| --------------------- | --------------------------------------- | ------- |
| `--modules <list>`    | 사용할 모듈 목록(쉼표 구분 또는 `all`)               | `all`   |
| `--read-only`         | 조회 전용 모드. 주문·입출금 차단                     | `false` |
| `--no-log`            | 실행 로그 비활성화(기본적으로 실행 로그는 활성화되어 있습니다)     | —       |
| `--log-level <level>` | 로그 레벨(`error`, `warn`, `info`, `debug`) | `info`  |
| `--verbose`           | 상세 요청 로그를 stderr에 출력                    | `false` |
| `--help`              | 도움말 출력                                  | —       |
| `--version`           | 버전 출력                                   | —       |

### 모듈 단위 노출

```json
// 시세 조회만 활성화
"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 페이지의 실행 로그](cli#실행-로그) 섹션을 참고하세요.

## 환경 변수

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

## 더 알아보기

<Cards>
  <Card title="CLI" href="cli" icon="fa-terminal">
    터미널에서 `bithumb` 명령으로 시세 조회·주문·입출금을 실행합니다.
  </Card>

  <Card title="Skills" href="skills" icon="fa-wand-magic-sparkles">
    Claude Code, Codex 같은 AI 에이전트에 빗썸 Skill을 등록해 여러 단계 작업을 자동으로 처리합니다.
  </Card>

  <Card title="AI 트레이드 킷 시작하기" href="ai-트레이드-킷-시작하기" icon="fa-rocket">
    AI 트레이드 킷의 개요와 시작 가이드를 안내합니다.
  </Card>
</Cards>