convez.ai
MCP ServerIntegração & APIsIntermediário
dvgamerr-app

Bitkub MCP Server

dvgamerr-app/gokub-mcp

MCP server Go para trading na Bitkub com Claude Desktop

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-mcp

1 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

Estrelas
4
Forks
2
Acompanhando
1
Saúde
37%
Último commit
há 3 dias
Versão
v1.3.1
Issues abertas
1
Contribuidores
2

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

CodeQL Go Version License Discord

Model Context Protocol server for Bitkub Cryptocurrency Exchange API

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

logo

Features • Installation • API Tools • Configuration • Community


✨ Features

🎯 Core Features

  • ✅ MCP 2026-07-28 - Built with the official Go SDK
  • 🌐 Streamable HTTP - Stateless /mcp endpoint
  • 🔐 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

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 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 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 vendor first 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.

EndpointPurposeMethod
http://localhost:3000/mcpStateless MCP requestsPOST

🛠️ 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 with adx_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 marked method=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 exposes trend_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. top3 remains the absolute ROC ranking; relative_roc and outperforms_benchmark are 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_atr is the gate input; trend_atr and entry_atr retain their own timeframe meanings. Stale actual source candles block analysis even if synthetic bars fill the grid.
  • check_exit_signals returns 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

VariableRequiredPurpose
BTK_APIKEYfor trading/walletBitkub API key
BTK_SECRETfor trading/walletBitkub API secret
PORTno (default 3000)Streamable HTTP port (-serv mode)
TRADES_FILEno (default trades.json)trade-journal file path
LOG_FORMATno (default JSON)Set to text for console-friendly logs
LOG_LEVELno (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

CategoryRate LimitNote
📈 Market Data100 req/secPublic endpoints
💱 Trading Operations150-200 req/secAuthenticated 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_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

🔧 Official MCP Go SDK

💎 Go-Bitkub SDK

📖 Bitkub Official API Docs

🤖 MCP 2026-07-28 Specification

👥 Community

Discord

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

Ver o original no GitHub

Bom para

Relacionados