English | 한국어

빗썸 자산 대시보드 킷

빗썸 계좌의 잔고·평가손익·자산 비중·일별 손익·주문·입출금 내역을 AI에 연결하는 MCP 서버입니다. AI에게 “내 자산으로 대시보드를 만들어줘”라고 하면 화면 설정을 저장하고 로컬 대시보드를 띄웁니다.

• 외부 의존성 0개 — Node.js 22.13 이상 내장 기능만 사용합니다. npm install이 필요 없습니다.

• 조회 전용 — 주문·취소·출금 도구가 없습니다. 쓰기는 이 컴퓨터의 대시보드 화면 설정뿐입니다.

• 키는 이 컴퓨터에만 — 키를 도구 입력으로 받지 않고 브라우저나 AI로 보내지 않습니다.

단일 사용자 로컬 조회용 개발 시제품입니다. 빗썸 공식 패키지와 별개이며 npm에는 배포하지 않았습니다.

구성 요소

공통 계산·빗썸 연결은 src/, 대시보드 화면은 web/에 있습니다. 서버 없이 바로 열리는 샘플은 examples/sample-dashboard.html입니다.

Related MCP server: OKX MCP Server

시작하기

Node.js 22.13 이상이 필요합니다. 외부 패키지가 없어 npm install 없이 바로 실행됩니다.

git clone https://github.com/realmi-lab/asset_kit.git
cd asset_kit
npm run demo

내 자산 대시보드 열기 — 데모는 키 없이 실행되며 잔고·시세·추이가 모두 합성 예시입니다. 실제 계좌 연결은 아래 인증을 참고하세요.

MCP

mcp/의 서버를 MCP 클라이언트에 등록합니다. 외부 패키지가 없어 설치 과정이 없습니다. 경로는 저장소를 내려받은 실제 절대 경로로 바꾸세요.

Claude Code (프로젝트 루트의 .mcp.json, 또는 전역 설정은 ~/.claude.json):

{
  "mcpServers": {
    "bithumb-assets": {
      "command": "node",
      "args": ["/absolute/path/to/asset_kit/mcp/index.js"]
    }
  }
}

키 없이 먼저 체험하려면 args 끝에 "--demo"를 추가합니다.

사용 예시

• “내 빗썸 잔고와 평가손익을 보여줘.”

• “이번 달 일별 손익을 알려줘.”

• “지난달 원화 입출금 내역을 정리해줘.”

• “BTC·ETH만 묶은 대시보드 만들고 열어줘.”

Codex·Cursor·VS Code·Windsurf·Claude Desktop 설정, 기능 모듈별 도구 14개, 실행 옵션(--modules, --read-only), 대시보드 만들기 순서는 MCP 문서를 참고하세요.

인증

1. 빗썸 API 관리에서 조회 권한과 허용 IP를 설정합니다.

2. 이 폴더에서 실행합니다. 입력한 키는 화면에 보이지 않고 ~/.bithumb-asset-kit/credentials.json(권한 0600)에만 저장됩니다.

node cli/asset-kit.js config init
node cli/asset-kit.js doctor

환경 변수 BITHUMB_ACCESS_KEY, BITHUMB_SECRET_KEY가 있으면 그 값을 먼저 씁니다. .env 파일은 --env-file .env로 지정합니다. 키를 AI 채팅에 입력하지 마세요. MCP로 조회한 계좌 데이터는 연결한 AI 서비스에서 처리될 수 있습니다.

대시보드

npm run demo   # 합성 데이터 → http://127.0.0.1:4319
npm start      # 실제 계좌

• 화면(보드)을 여러 개 만들어 탭으로 전환합니다. 화면마다 위젯 순서·자산 범위·추이 기간(7/30/90일·1년)·자동 갱신을 저장합니다.

• 자산 추이 ↔ 일별 손익 달력, 자산 상세(30일 시세), 요약 보기, 금액 숨기기, CSV·설정 내보내기/가져오기를 제공합니다.

• 거래·입출금은 종류와 기간을 고르면 페이지를 이어 조회합니다.

• 화면을 직접 고치려면 web/을 수정하고 새로고침합니다. 빌드 과정이 없습니다. 다른 폴더의 화면은 --web-dir로 띄웁니다.

• 샘플 HTML은 npm run sample로 다시 만듭니다. 합성 데이터만 들어갑니다.

CLI

node cli/asset-kit.js portfolio --demo
node cli/asset-kit.js explain --symbols BTC,ETH
node cli/asset-kit.js history --days 30 --daily
node cli/asset-kit.js market --symbol BTC
node cli/asset-kit.js records --kind orders --from 2026-09-01 --to 2026-09-30
node cli/asset-kit.js boards create --name "장기 보유" --symbols BTC,ETH
node cli/asset-kit.js skill install --path ./my-project

전체 명령은 node cli/asset-kit.js --help입니다. 데이터 명령은 JSON을 출력하고, 오류는 stderr JSON과 종료 코드 1입니다.

Skills

skills/bithumb-asset-dashboard: 연결 확인 → 조회 → 범위 확인 → 대시보드 저장·열기 순서를 안내합니다. asset-kit skill install --path <프로젝트>는 .claude/skills/에, --target agents는 .agents/skills/에 설치합니다.

계산 기준과 범위

• 수량은 가용 + 주문 중입니다. 금액은 BigInt 십진 계산으로 부동소수점 오차가 없고, 응답은 십진 문자열, 미확인 값은 null입니다.

• 평가손익은 현재 보유분의 API 평균 매수가 기준이며 수수료·실현손익을 포함하지 않습니다. 원화 마켓이 없는 코인은 BTC 마켓 가격 × KRW-BTC로 평가합니다.

• 추이·일별 손익은 조회할 때마다(최대 5분에 한 번) 이 컴퓨터에 기록한 평가금액이라 입출금이 포함됩니다. 과거를 소급해 만들지 않습니다.

• 전체 기간 실현손익·세금·스테이킹/대여 상품은 제공하지 않습니다.

보안

• 대시보드는 127.0.0.1에만 열리며 Host·Origin을 검사합니다. 화면 설정 저장은 같은 출처의 JSON 요청과 전용 헤더가 있어야 합니다.

• 기록·화면 설정·키 파일은 ~/.bithumb-asset-kit(폴더 0700, 파일 0600)에 있고 ASSET_KIT_DATA_DIR로 바꿀 수 있습니다.

• 빗썸 응답 형식이 바뀌면 추정하지 않고 멈춥니다. 429·5xx·네트워크 오류는 새 서명으로 최대 2회 재시도합니다.

개발

npm test         # 테스트 30개, 설치 불필요
npm run sample   # 샘플 HTML 다시 만들기

mcp/index.js        MCP 서버(JSON-RPC 2.0 stdio)와 도구 정의
cli/asset-kit.js    CLI
skills/             AI 작업 가이드
src/                계산(portfolio·decimal), 빗썸 연결(bithumb), 기록(history), 화면 설정(boards), 로컬 서버(server)
web/                대시보드 화면(index.html·app.js·styles.css·로고)
examples/           샘플 HTML과 생성 스크립트
test/               자동 테스트

검증: 공식 MCP SDK 클라이언트(1.32.1)로 프로토콜 협상과 도구 호출 호환성을 확인했습니다. 실제 계좌 API 키 연동은 아직 검증하지 않았습니다.

참고

빗썸 공식 AI 트레이드 킷의 MCP·CLI·Skills 제공 방식을 참고했습니다. 공식 문서: MCP · CLI · Skills

라이선스

MIT