Bitkub MCP Server
dvgamerr-app/gokub-mcp
MCP server Go para trading na Bitkub com Claude Desktop
Ver no GitHubServidor Model Context Protocol (MCP) para a API da exchange de criptomoedas Bitkub, construído em Go. Integra Claude Desktop com a plataforma de trading Bitkub, permitindo consultas de saldos, transações, dados de mercado em tempo real e gerenciamento de ordens através do protocolo MCP.
Instalação
npx convez-ai dvgamerr-app/gokub-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consultar saldos e histórico de transações em carteira Bitkub
- Obter dados de mercado em tempo real (tickers, profundidade de livro de ordens)
- Monitorar e gerenciar ordens abertas na exchange
- Automatizar análise de posições de criptomoedas via Claude
Veredito

Implementação sólida de MCP server em Go com suporte completo à API v3 do Bitkub e segurança via HMAC SHA256. Excelente para traders e desenvolvedores que buscam automatizar operações de criptomoedas integradas ao Claude, embora limitado ao ecossistema Bitkub.
README
A tradução para o português deste README ainda está na fila.
🚀 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 2026-07-28 - Built with the official Go SDK
- 🌐 Streamable HTTP - Stateless
/mcpendpoint - 🔐 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-tradeplaybook plugin. Steps 3–5 are the important part.
1️⃣ Install the MCP server
Requires Go 1.25.5 or newer.
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 (Streamable HTTP 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 ., 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 userto make it global across all projects (default scope is project-local.mcp.json). - It runs over stdio by default — no extra flags. Verify with
/mcpin 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 stateless Streamable HTTP 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 a Streamable HTTP client at http://localhost:8080/mcp. 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 vendorfirst and build with-mod=vendor.
🎮 Usage
Standard input/output mode
This is the default transport for locally registered Claude Code and Codex clients:
go run .
Streamable HTTP Server Mode
# Default port 3000
go run . -serv
# Custom port
PORT=9000 go run . -serv
Default port is 3000 (override with
PORT). Docker image defaults to 8080.
| Endpoint | Purpose | Method |
|---|---|---|
http://localhost:3000/mcp | Stateless MCP requests | POST |
🛠️ Available Tools
Native trade analysis (no client scripts)
Call analyze_market_trades with trend_resolution: 240, entry_resolution: 15,
target_net_percent: 2, and risk_percent: 2 to scan every liquid exchange-only THB
pair. It checks closed fresh candles, regime/EMA, relative strength, ATR, entry
signals, available THB, fees, pending orders and journal positions. Results include
all pairs, explicit rejection/error reasons and fee/spread-aware plans. It never
places orders. Check complete and analysis_error_count before concluding that
all pairs were analyzed successfully.
For individual steps, use get_market_screener(exchange_only=true, limit=0) to
return every passing pair, and get_historical_candles(..., closed_only=true) to
exclude forming candles and fill no-trade gaps with the previous close and zero
volume. Filled bars carry synthetic: true (also a CSV column); history_metadata
records the last actual candle and filled count. Duplicate timestamps keep the last
API update without adding volumes. The analyzer blocks entry on zero-volume bars;
unavailable/out-of-window source data still errors. Completed candles are now the
default; request closed_only=false explicitly for forming candles. Supply the same
as_of Unix timestamp to align separate requests. Multi-symbol history fails explicitly
if any requested symbol is unavailable.
42 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 · analyze_chart
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 · backtest_signals · pnl_with_fees · calculate_capm
calculate_capm is an assumption-based asset-pricing calculator, not a chart forecast.
Analysis semantics and historical evaluation
- Prefer completed OHLCV candles for
check_market_regime. Wilder ADX requires at least 28 candles; price-only and close-only inputs remain supported withadx_available=false. OHLC regimes require ADX ≥25, matching +DI/-DI direction and net price direction; up-bar counts cannot bypass weak ADX. The legacy close-only assessment is explicitly markedmethod=close_only_fallback. Regime scores are heuristic scores, not win probabilities. - Indicator and signal outputs preserve price precision. EMA output preserves its
input-aligned array; ignore warmup zeros before
valid_from_index. It exposestrend_available; exactly one seeded EMA has no trend. Flat-price RSI is defined as 50 (neutral). - Malformed OHLC ranges, non-positive prices and invalid timestamps fail explicitly. Timestamps are optional for existing indicator callers; when supplied they must be present on every row, increasing and on a regular grid. Signal callers must supply completed candles; breakout requires volume, pullback/exit require open and volume. Synthetic latest bars cannot confirm entries or exit decisions.
- Pullback requires a preceding decline, bullish price recovery and rising RSI in the configured bounce zone. A candle merely closing near its high is insufficient.
- Relative-strength ranking requires benchmark data.
top3remains the absolute ROC ranking;relative_rocandoutperforms_benchmarkare separate. The native workflow requires both top-three rank and outperformance (the benchmark itself is allowed), and uses one cutoff for all candle requests. Direct price arrays must be aligned by the caller before ranking. - The native 2–6% volatility gate always uses daily ATR(14), independent of the
selected trend timeframe.
daily_atris the gate input;trend_atrandentry_atrretain their own timeframe meanings. Stale actual source candles block analysis even if synthetic bars fill the grid. check_exit_signalsreturns an error when data cannot support an exit decision, including insufficient history and a latest bar with no actual trades.
Call backtest_signals(candles, resolution, as_of, strategy="breakout") with
221–10000 timestamped completed OHLCV candles. It uses 220 candles for warmup,
then evaluates fixed rules in up to three default chronological
folds with expanding history. Optional inputs: folds (1–10), fee_percent
(per side, default 0.25), slippage_percent (per side including spread, default
0.1), and reward_risk (gross distance ratio, default 2).
Signals use prior candles only. Simulated entries fill at the next actual open;
stops gap to the open, and a candle touching both stop and target counts as a stop.
Folds close remaining positions only on an actual final bar. A no-trade tail
leaves unresolved_positions and complete=false, without looking ahead to choose
an earlier exit. Outputs include
trade records, per-fold and total win rates, approximate Wilson intervals, average
net returns/R, equal-notional profit factor, and explicitly hypothetical
full-notional closed-trade compounded returns/drawdown. They do not measure
intratrade or live-portfolio drawdown.
No trades produces null rates, not evidence of accuracy. This evaluates entry
signals only: it does not reproduce the live multi-symbol regime/ranking/ATR gate,
portfolio sizing, exchange rounding or limit-order fills. It performs no parameter
optimization and does not establish calibrated prediction probabilities.
Supported fixed-rule experiments: breakout, pullback, macd_cross (12/26/9),
supertrend_flip (10/3), bollinger_breakout (20/2), and ema_crossover (20/50).
Chart crossover experiments use 1.5×ATR14 initial stops and the same costs/fill/target
model. They do not become live-entry conditions automatically.
Call analyze_chart(candles, resolution, as_of) with 220–10000 completed timestamped
OHLCV bars for EMA/RSI/ATR/DMI, MACD, Bollinger Bands, Supertrend and anchored VWAP
readings. Default VWAP anchor is the last candle's UTC midnight; optional
vwap_anchor must be a covered candle-open timestamp. Uncovered anchors or no
volume return an unavailable VWAP. A daily anchor on daily bars is not meaningful.
Outputs disclose SMA-seeded EMA and ATR initialization differences from TradingView;
these are standard formulas, not a claim of exact platform parity.
Native trade analysis includes these entry-timeframe diagnostics as chart, and
requests 1000 trend candles to reduce EMA200 seed sensitivity. Existing risk gates
and exchange rounding remain required. The new indicators do not form an extra
majority-vote confidence score.
See TradingView research and recorded comparison for primary sources, keep/add/defer decisions, numerical conventions and a reproducible 48-case public-market snapshot. It does not establish any universally best indicator.
🧠 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, fee-aware net-profit targets).
→ Install it in step 5 of Installation. Details:
plugins/bitkub-trade.
⚙️ Configuration
🔐 Environment variables
| Variable | Required | Purpose |
|---|---|---|
BTK_APIKEY | for trading/wallet | Bitkub API key |
BTK_SECRET | for trading/wallet | Bitkub API secret |
PORT | no (default 3000) | Streamable HTTP port (-serv mode) |
TRADES_FILE | no (default trades.json) | trade-journal file path |
LOG_FORMAT | no (default JSON) | Set to text for console-friendly logs |
LOG_LEVEL | no (default info) | trace, debug, info, warn, error, fatal, or panic |
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 your MCP client accepts a remote server URL, point it at the Streamable HTTP endpoint:
{
"mcpServers": {
"gokub": { "type": "http", "url": "http://localhost:3000/mcp" }
}
}
For Claude Code / Codex, prefer claude mcp add / codex mcp add (stdio) above.
🧪 Development and verification
go mod verify
go test ./...
go vet ./...
go build ./...
The default test suite is deterministic and excludes tools/get_historical_candles_live_test.go.
The opt-in live build tag calls public Bitkub market-data endpoints and should only be
used intentionally. Do not run authenticated wallet or order flows as automated tests
against real credentials.
📁 Project Structure
gokub-mcp/
├── 📄 main.go # MCP Server entry point (Streamable HTTP) + tool registration
├── 🐳 Dockerfile # Streamable HTTP server image
├── 📂 tools/ # 40 MCP tools (+ unit tests)
├── 📂 prompts/ # trading_strategy, market_analysis prompts
├── 📂 resources/ # bitkub://symbols, bitkub://ticker/{symbol}
├── 📂 utils/ # Utility functions
├── 📂 docs/ # Project images and supporting documentation
├── 📂 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
| Category | Rate Limit | Note |
|---|---|---|
| 📈 Market Data | 100 req/sec | Public endpoints |
| 💱 Trading Operations | 150-200 req/sec | Authenticated endpoints |
📚 Bitkub API Docs สำหรับข้อมูลเพิ่มเติม
🚀 Roadmap
✅ Completed
- Bitkub API golang library + MCP Server (Streamable HTTP + stdio)
- 40 trading tools — foundation, indicators, entry signals, risk, orders, management, logging, native market analysis
- Risk-based position sizing + pre-trade
validate_trade_setupgate - Client-side stop worker (Bitkub has no native stop/OCO)
- Trade journal + expectancy (flat-file
trades.json) -
bitkub-tradeplaybook plugin — installable in Claude Code & Codex
🚧 In Progress / Next
-
git pushthe 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 2026-07-28 Specification
👥 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!