🚀 Bitkub MCP Server

Model Context Protocol server for Bitkub Cryptocurrency Exchange API

เชื่อมต่อ Claude Desktop กับ Bitkub Exchange ผ่าน MCP Protocol

Features • Installation • API Tools • Configuration • Community

✨ Features

🎯 Core Features

• ✅ MCP Server - Built with mcp-go
• 🌐 HTTP/SSE - Real-time communication
• 🔐 Secure - HMAC SHA256 signature
• 💰 Wallet - View balances & transactions

🚀 Developer Experience

• 💎 Go-Bitkub SDK - Full API v3 support
• 🧠 Integration - with Claude Desktop
• 📊 Market Data - Real-time ticker & depth
• 📖 Order - Track open orders

🔧 Installation

Fastest path: install the server → register it as an MCP server in Claude Code / Codex → install the bitkub-trade playbook plugin. Steps 3–5 are the important part.

1️⃣ Install the MCP server

go install github.com/dvgamerr-app/gokub-mcp@latest

This installs gokub-mcp to $(go env GOPATH)/bin by default.

Windows default path:

# PowerShell
Write-Output "$env:USERPROFILE\go\bin\gokub-mcp.exe"

:: cmd.exe
echo %USERPROFILE%\go\bin\gokub-mcp.exe

# NuShell
$env.USERPROFILE | path join go bin gokub-mcp.exe

# macOS/Linux default
$(go env GOPATH)/bin/gokub-mcp

For local development from a clone:

git clone https://github.com/dvgamerr-app/gokub-mcp.git
cd gokub-mcp
go install .

Prefer containers? Use 🐳 Docker (HTTP/SSE mode).

2️⃣ Credentials

The server reads BTK_APIKEY / BTK_SECRET from its environment — pass them when you register the server (steps 3–4), so no .env file is required. For a plain local go run main.go, a .env in the repo root still works:

BTK_APIKEY=your_api_key
BTK_SECRET=your_secret_key

3️⃣ Register the MCP server in Claude Code

The current way is the claude mcp add CLI (replaces hand-editing JSON). Pass the env inline with -e:

claude mcp add bitkub \
  -e BTK_APIKEY=your_api_key \
  -e BTK_SECRET=your_secret_key \
  -- "$(go env GOPATH)/bin/gokub-mcp"

Windows:

# PowerShell
claude mcp add bitkub `
  -e BTK_APIKEY=your_api_key `
  -e BTK_SECRET=your_secret_key `
  -- "$env:USERPROFILE\go\bin\gokub-mcp.exe"

:: cmd.exe
claude mcp add bitkub -e BTK_APIKEY=your_api_key -e BTK_SECRET=your_secret_key -- "%USERPROFILE%\go\bin\gokub-mcp.exe"

# NuShell
let gokub = ($env.USERPROFILE | path join go bin gokub-mcp.exe)
claude mcp add bitkub -e BTK_APIKEY=your_api_key -e BTK_SECRET=your_secret_key -- $gokub

• Add -s user to make it global across all projects (default scope is project-local .mcp.json).
• It runs over stdio by default — no extra flags. Verify with /mcp in a session.

4️⃣ Register the MCP server in Codex

codex mcp add gokub \
  --env BTK_APIKEY=your_api_key \
  --env BTK_SECRET=your_secret_key \
  -- "$(go env GOPATH)/bin/gokub-mcp"

Windows:

# PowerShell
codex mcp add gokub `
  --env BTK_APIKEY=your_api_key `
  --env BTK_SECRET=your_secret_key `
  -- "$env:USERPROFILE\go\bin\gokub-mcp.exe"

:: cmd.exe
codex mcp add gokub ^
  --env BTK_APIKEY=your_api_key ^
  --env BTK_SECRET=your_secret_key ^
  -- "%USERPROFILE%\go\bin\gokub-mcp.exe"

# NuShell
let gokub = ($env.USERPROFILE | path join go bin gokub-mcp.exe)
codex mcp add gokub --env BTK_APIKEY=your_api_key --env BTK_SECRET=your_secret_key -- $gokub

…or edit ~/.codex/config.toml directly:

[mcp_servers.gokub]
command = "/absolute/path/to/gokub-mcp"
args = []

[mcp_servers.gokub.env]
BTK_APIKEY = "your_api_key"
BTK_SECRET = "your_secret_key"

Verify with /mcp inside Codex.

5️⃣ Install the trading playbook plugin (skill)

The tools are the hands; the bitkub-trade plugin is the brain — the strategy playbook + guardrails. The repo doubles as a plugin marketplace for both clients:

# Claude Code
/plugin marketplace add dvgamerr-app/gokub-mcp
/plugin install bitkub-trade@gokub-mcp

# Codex
codex plugin marketplace add dvgamerr-app/gokub-mcp
codex plugin add bitkub-trade@gokub-mcp

See plugins/bitkub-trade for details.

🐳 Docker

Runs the server in HTTP/SSE mode (good for a shared/remote server; for a local client that spawns the binary over stdio, use the native build above):

docker build -t gokub-mcp .
docker run --rm -p 8080:8080 \
  -e BTK_APIKEY=your_api_key \
  -e BTK_SECRET=your_secret_key \
  gokub-mcp

Then point an SSE-capable client at http://localhost:8080/sse. Override the port with -e PORT=9000 -p 9000:9000.

The build fetches Go deps from the module proxy (needs internet). For an offline / hermetic build, run go mod vendor first and build with -mod=vendor.

🎮 Usage

HTTP/SSE Server Mode

# Default port 3000
go run main.go

# Custom port
PORT=9000 go run main.go

Default port is 3000 (override with PORT). Docker image defaults to 8080.

🛠️ Available Tools

39 tools covering the full long-only swing-trading workflow (screen → analyze → size → place → manage → log).

get_wallet_balance · get_ticker · get_market_depth · get_my_open_orders · get_symbols · get_symbol_rules · get_fee_schedule

calculate_spread · calculate_liquidity_depth · get_market_screener · get_historical_candles · extract_close_prices

calculate_ema · calculate_roc · calculate_atr · calculate_rsi · check_market_regime · calculate_capm

detect_breakout_signal · detect_pullback_signal · calculate_relative_strength_rank

calculate_position_size · validate_trade_setup · round_to_exchange_rules

place_limit_order · place_stop_limit_order · cancel_order · get_order_status

check_trade_pnl · calculate_trailing_stop · check_exit_signals · client_side_stop_worker (Bitkub has no native stop/OCO — client-side trigger)

log_trade_entry · log_trade_exit · calculate_expectancy · get_trade_history (flat-file journal trades.json, override with TRADES_FILE)

get_market_overview · simulate_trade · pnl_with_fees

🧠 Trading Playbook (Plugin / Skill)

The tools are the hands; the bitkub-trade plugin is the brain — a playbook skill that encodes the strategy (screen → regime → relative-strength → ATR → signal → size → validate gate → round → place → manage → log) and the hard guardrails (≤2% risk/trade, long-only, no entry unless can_trade=true, client-side stop, TP ≥2R).

→ Install it in step 5 of Installation. Details: plugins/bitkub-trade.

⚙️ Configuration

🔐 Environment variables

Pass keys when you register the MCP server (see Installation steps 3–4) — that's preferred over a committed .env. Public market-data tools work without keys; wallet/order tools need them.

⚠️ Keep secrets in env vars / your client config, never commit .env (it's gitignored).

If you run the HTTP server (or the Docker image) and use the Claude Desktop app, point it at the SSE endpoint:

{
  "mcpServers": {
    "gokub": { "url": "http://localhost:3000/sse", "transport": "sse" }
  }
}

Windows: %APPDATA%\Claude\claude_desktop_config.json · Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

For Claude Code / Codex, prefer claude mcp add / codex mcp add (stdio) above.

📁 Project Structure

gokub-mcp/
├── 📄 main.go                      # MCP Server entry point (HTTP/SSE) + tool registration
├── 🐳 Dockerfile                   # HTTP/SSE server image
├── 📂 tools/                       # 39 MCP tools (+ unit tests)
├── 📂 prompts/                     # trading_strategy, market_analysis prompts
├── 📂 resources/                   # bitkub://symbols, bitkub://ticker/{symbol}
├── 📂 utils/                       # Utility functions
├── 📂 docs/                        # ASSIGNMENT.md (spec & build progress)
├── 📂 plugins/bitkub-trade/        # bitkub-trade plugin (playbook skill)
│   ├── .claude-plugin/plugin.json  # Claude manifest
│   ├── .codex-plugin/plugin.json   # Codex manifest
│   └── skills/playbook/SKILL.md    # shared trading playbook
├── 📂 .claude-plugin/              # Claude plugin marketplace
└── 📂 .agents/plugins/             # Codex plugin marketplace

📊 API Rate Limits

📚 Bitkub API Docs สำหรับข้อมูลเพิ่มเติม

🚀 Roadmap

✅ Completed

• Bitkub API golang library + MCP Server (HTTP/SSE + stdio)
• 39 trading tools — foundation, indicators, entry signals, risk, orders, management, logging
• Risk-based position sizing + pre-trade validate_trade_setup gate
• Client-side stop worker (Bitkub has no native stop/OCO)
• Trade journal + expectancy (flat-file trades.json)
• bitkub-trade playbook plugin — installable in Claude Code & Codex

🚧 In Progress / Next

• git push the plugin so the marketplaces resolve from GitHub
• Optional MCP prompts/resources for non-Claude/Codex clients
• Backtesting over OHLCV history

🎯 Planned Features

• Rebalancing / Grid strategy presets
• Docker image + WebSocket real-time data

📚 References

🔧 MCP-Go Framework

💎 Go-Bitkub SDK

📖 Bitkub Official API Docs

🤖 Protocol MCP Spec

👥 Community

Join our community to discuss, get help, and share your trading strategies!

Made with ❤️ by dvgamerr-app

⭐ Star this repo if you find it helpful!

Report Bug • Request Feature • Contribute