kainext-binance-mcp

Let an AI assistant read Binance spot markets, analyze them, and propose real-money trades — while a separate, human-gated process is the only thing that can ever execute. The model never holds a trade key, and nothing moves without a physical click.

The gate. Every order renders exactly what will execute — and the default button is Cancel.

kainext-binance-mcp is a Model Context Protocol server that connects any MCP client (Claude Code, Claude Desktop, …) to a Binance spot account. It exposes 25 tools, 5 analyst prompts and 8 knowledge resources spanning live market data, technical indicators, news & sentiment, derivatives positioning, market structure, portfolio/risk analytics, transparent trading signals, and two-phase order execution with a human in the loop — a complete, honest crypto analysis consultant in one install.

It is built around one uncompromising idea: treat the language model as untrusted. Even a fully prompt-injected or malfunctioning model cannot move your funds, because it has neither the credential nor the authority to do so. See SECURITY.md for the full threat model.

⚠️ Real money. On mainnet, every order moves actual funds. Always start on testnet and switch to mainnet only once everything is verified. ✅ Execution works on every OS (v1.2): native dialog on macOS, a local web confirmation page elsewhere, or a TTY prompt for headless boxes — see Confirmation backends.

Why this exists

LLM agents are great at reasoning about markets and terrible at being trusted with irreversible, money-moving actions. Most "AI trading" tooling hands the model an API key and hopes for the best. This project takes the opposite stance: the AI gets rich, read-only context and a way to propose an action, but a human holds the trigger and a separate process holds the key. You get the upside of an AI co-pilot for spot trading without surrendering custody or control.

Security model — the headline feature

Two processes, least privilege, human-in-the-loop:

Releases are published to PyPI via trusted publishing and carry Sigstore digital attestations (verify any file at pypi.org/integrity/): what you install is provably what this repository's release workflow built.

sequenceDiagram
    participant AI as AI model (untrusted)
    participant S as MCP server<br/>(read-only key)
    participant C as Confirmer<br/>(trade key)
    participant H as You (human)
    participant B as Binance

    AI->>S: binance_spot_order_propose(...)
    S->>S: pre-validate vs symbol filters
    S->>C: canonical fields (local IPC socket)
    S-->>AI: intent_id (no order placed yet)
    C->>H: native dialog with exact fields ⚠️
    H-->>C: physical click: Confirm / Cancel
    C->>C: re-validate
    C->>B: execute (only if confirmed)
    AI->>S: binance_spot_order_status(intent_id)
    S-->>AI: pending → executed / rejected / expired

To execute one order you need both the trade key (isolated in the confirmer) and your physical click. The model has neither. Defense in depth on top of that:

• On mainnet, the server aborts at startup if its read key can trade.
• The confirmer aborts at startup if the trade key has withdrawals/transfer/margin/futures permissions or no IP whitelist.
• Withdrawals and transfers are permanently out of scope — no key enables them.
• Single-tenant: one server+confirmer pair serves exactly one account; run separate pairs for separate accounts.

Tools (25)

Read (5 · read key · no gate)

Market data — layer 2 (4 · read key · 100% read-only)

News & sentiment — layer 3 (2 · public RSS · no API key · 100% read-only)

Signals — layer 4 (3 · read key · propose, never execute)

Analyst — layers 5/6 (5 · read key + free public APIs · 100% read-only)

Write — two-phase (4 · spot only · the server never executes)

The read, market-data, news, and signal tools work without the confirmer. The *_propose tools require the confirmer to be running.

The knowledge layer — what makes it a consultant

Tools fetch data; knowledge tells the model how to think about it. The server ships its methodology through the two MCP surfaces most servers ignore:

Resources (kb://…) — read them from any MCP client:

Prompts — complete playbooks that orchestrate the tools (in Claude Code they appear as slash commands): portfolio_review, asset_thesis, market_briefing, risk_check, dca_plan. Every playbook grounds itself in kb://discipline first, and the server's instructions tell clients to read the doctrine before giving any investment analysis.

Quickstart

Prerequisites: Python 3.12+, uv, and (for execution) macOS.

1. Create the API key(s) on Binance

Go to Binance → API Management. The design uses two keys for least privilege:

1. Read-only (used by the server): Enable Reading ON; everything else OFF.
2. Trade (used by the confirmer): Enable Spot & Margin Trading ON; withdrawals, universal/internal transfer, margin, futures OFF; IP whitelist mandatory. The confirmer aborts on mainnet if any dangerous permission is on or the IP restriction is off.

On testnet (testnet.binance.vision), a single key serves both roles — there are no granular permissions or IP whitelist there.

2. Set environment variables

🔒 Hard rule: the trade key never goes in .mcp.json or any environment your AI client inherits. It lives only in the confirmer's shell.

3. Add the server to your MCP client

.mcp.json (Claude Code style). Only the read key + BINANCE_ENV:

{
  "mcpServers": {
    "binance": {
      "command": "uvx",
      "args": ["kainext-binance-mcp"],
      "env": {
        "BINANCE_ENV": "${BINANCE_ENV}",
        "BINANCE_READ_API_KEY": "${BINANCE_READ_API_KEY}",
        "BINANCE_READ_API_SECRET": "${BINANCE_READ_API_SECRET}"
      }
    }
  }
}

${VAR} placeholders are resolved from your shell. If a variable arrives unexpanded, the server aborts with a clear message — export the variables before launching your client.

Installing from git instead of PyPI? Use "args": ["--from", "git+https://github.com/Alejandrehl/kainext-binance-mcp@v1.0.0", "kainext-binance-mcp"] (pin a tag; git+https works without any GitHub credentials).

4. Run the confirmer (required to execute)

In a separate terminal, with the trade key exported:

export BINANCE_ENV=testnet
export BINANCE_TRADE_API_KEY="...your trade key..."
export BINANCE_TRADE_API_SECRET="...your trade secret..."

uvx kainext-binance-mcp-confirmer  # or: uvx --from "git+https://github.com/Alejandrehl/kainext-binance-mcp@v1.0.0" kainext-binance-mcp-confirmer

It listens on a local Unix socket. When the AI proposes an order, a native dialog appears with the exact fields (symbol, side, type, effective quantity, price, timeInForce, estimated notional, and a TESTNET / ⚠️ REAL MONEY banner). The default button is Cancel; the order executes only when you click Confirm.

Confirmation backends

The confirmer decides how the human approves, via BINANCE_CONFIRM_MODE:

Every backend keeps the same invariants: the text is rendered from the exact canonical order that will execute, the default is deny, and a 45s timeout denies.

Watch mode — get notified, never auto-trade

kainext-binance-mcp-watch is a third process that holds no keys at all (public endpoints only) and can execute nothing. It checks your triggers on an interval and notifies (desktop notification + optional webhook) on threshold crossings — price, daily close (completed candles only), funding rate, Fear & Greed:

mkdir -p ~/.config/kainext-binance-mcp
cp examples/watch.example.toml ~/.config/kainext-binance-mcp/watch.toml  # edit it
kainext-binance-mcp-watch

Testnet-first (recommended)

1. Generate keys at testnet.binance.vision (login with GitHub → Generate HMAC_SHA256 Key) and request faucet funds.
2. Export BINANCE_ENV=testnet and the testnet keys.
3. Exercise the full flow with fake money before touching mainnet.

Mainnet = real money

On mainnet, the confirmer re-validates against live symbol filters, shows the ⚠️ REAL MONEY banner, and waits for your click. Start with minimal order sizes. Execution uses the native dialog on macOS; on other platforms set BINANCE_CONFIRM_MODE=web (or tty).

Development

Requires Python 3.12+ and uv. See CONTRIBUTING.md for details.

uv venv --python 3.12
uv pip install -e ".[dev]"

uv run ruff check src/ tests/ examples/   # lint (the release gate)
uv run mypy                               # strict type checking
uv run pytest -q                          # tests + coverage (hard gate: 90% min)

The unit suite runs fully offline. Integration tests (-m integration) hit Binance testnet and skip cleanly without keys; the news test hits live RSS only with RUN_NETWORK_TESTS=1. CI runs lint + types + tests on ubuntu and macOS (the confirmer's target OS) across Python 3.12/3.13, plus pip-audit and CodeQL, on every push and PR. pre-commit install gets you the same ruff check locally.

Roadmap

• Migrate to MCP SDK 2.x (v1.0.0 pins mcp==1.29.0; 2.0 is a breaking API change).
• Additional order types and exchange surfaces beyond spot.
• Optional notification channels for proposal/execution events.

Research: is there an edge?

We backtested our own composite signal the hard way — out-of-sample walk-forward over ~51,000 real candles (4 pairs x 3 timeframes x 3 strategies, grid search on train windows, measured on unseen test windows, triple anti-lookahead). Result: 0 of 36 configurations showed a robust out-of-sample edge; in-sample "edges" were overfitting.

That is why every signal tool ships with a disclaimer: the signals are context, not alpha. Full write-ups and reproducible scripts: docs/research/ + examples/.

Disclaimer

This software is not financial advice and comes with no warranty (MIT). Trading cryptocurrencies can result in the loss of your entire capital. Signals, indicators, and backtests are informational; past performance does not predict future results. You are solely responsible for every order you confirm — that is exactly why the human gate exists.

Author

Built by Alejandro Exequiel Hernández Lara — founder of KaiNext. Part of KaiNext's MCP product line.

License

MIT © 2026 Alejandro Exequiel Hernández Lara (KaiNext)

_{mcp-name: io.github.Alejandrehl/kainext-binance-mcp}