README
ยถ
๐ 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
|
๐ Developer Experience
|
๐ง 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
๐ก Server Endpoints
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).
Foundation (7)
get_wallet_balance ยท get_ticker ยท get_market_depth ยท get_my_open_orders ยท
get_symbols ยท get_symbol_rules ยท get_fee_schedule
Market & Liquidity (5)
calculate_spread ยท calculate_liquidity_depth ยท get_market_screener ยท
get_historical_candles ยท extract_close_prices
Indicators (6)
calculate_ema ยท calculate_roc ยท calculate_atr ยท calculate_rsi ยท
check_market_regime ยท analyze_chart
Entry Signals (3)
detect_breakout_signal ยท detect_pullback_signal ยท calculate_relative_strength_rank
Position & Risk (3)
calculate_position_size ยท validate_trade_setup ยท round_to_exchange_rules
Order Management (4)
place_limit_order ยท place_stop_limit_order ยท cancel_order ยท get_order_status
Trade Management (4)
check_trade_pnl ยท calculate_trailing_stop ยท check_exit_signals ยท
client_side_stop_worker (Bitkub has no native stop/OCO โ client-side trigger)
Logging & Performance (4)
log_trade_entry ยท log_trade_exit ยท calculate_expectancy ยท get_trade_history
(flat-file journal trades.json, override with TRADES_FILE)
Helpers (5)
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).
๐ค Remote Streamable HTTP config
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
๐ง Official MCP Go SDK
๐ Go-Bitkub SDK
๐ค 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!
Report Bug โข Request Feature โข Contribute
Documentation
ยถ
There is no documentation for this package.