krmaazha-binance-mcp

About: Security-first Binance MCP server and multi-agent intelligence platform. Read market data, perform quantitative analysis, and propose spot orders behind human confirmation.
Tags: #mcp #model-context-protocol #binance #crypto #trading #multi-agent #quantitative-finance #spot-trading #futures #backtesting #ai-agents #claude #llm #fastmcp #algorithmic-trading

Let an AI assistant read Binance 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.

krmaazha-binance-mcp is a Model Context Protocol server that connects any MCP client (Claude Code, Claude Desktop, …) to a Binance account. It exposes 26 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 also ships an offline USD-M futures research engine (no tools, no keys, no network at import time) — see Futures research.

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 and PRIVACY.md for zero-knowledge data handling policies.

⚠️ 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 your 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 (26)

Read (5 · read key · no gate)

Market data — layer 2 (5 · 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 (7 · read key + free public APIs · 100% read-only)

Write — two-phase (4 · execution is 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.

Futures research

An offline USD-M futures research engine lives in krmaazha_binance_mcp.futures, behind the [research] extra. It is deliberately not an MCP surface:

• No tools, no prompts, no resources. Nothing about it reaches the model.
• Keyless. It reads Binance's public archives (data.binance.vision) with no API key at all — strictly less exposed than the signed spot path.
• Never imported by the server. Install without [research] and the server starts fine.
• Execution stays spot-only. This engine researches; it cannot place an order.

What it does today: builds a survivorship-bias-free panel of USD-M perpetuals from the public archives — 986 symbols, of which 306 USDT perps are already delisted — with point-in-time universe membership derived from the data itself. Three archive traps are handled explicitly and documented in futures/data.py: the CSV header changed between eras (2020 files have none), the current month is missing from the monthly archives, and today's candle is incomplete, which is lookahead in disguise.

The doctrine that governs it is kb://discipline rule 7 — leverage is admissible only inside a systematic strategy that has cleared every condition. See ROADMAP.md and docs/architecture.md.

Quickstart

Prerequisites: Python 3.12+ and uv. Execution works on every OS — see Confirmation backends.

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

Choose your client configuration below. Only the read-only key and BINANCE_ENV are passed:

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

{
  "mcpServers": {
    "binance": {
      "command": "uvx",
      "args": ["krmaazha-binance-mcp"],
      "env": {
        "BINANCE_ENV": "testnet",
        "BINANCE_READ_API_KEY": "YOUR_READ_API_KEY",
        "BINANCE_READ_API_SECRET": "YOUR_READ_API_SECRET"
      }
    }
  }
}

{
  "mcpServers": {
    "binance": {
      "command": "uvx",
      "args": ["krmaazha-binance-mcp"],
      "env": {
        "BINANCE_ENV": "testnet",
        "BINANCE_READ_API_KEY": "YOUR_READ_API_KEY",
        "BINANCE_READ_API_SECRET": "YOUR_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/KumailQazi/krmaazha-binance-mcp@v1.2.2", "krmaazha-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 krmaazha-binance-mcp-confirmer  # or: uvx --from "git+https://github.com/KumailQazi/krmaazha-binance-mcp@v1.2.2" krmaazha-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

krmaazha-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/krmaazha-binance-mcp
cp examples/watch.example.toml ~/.config/krmaazha-binance-mcp/watch.toml  # edit it
krmaazha-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,research]"       # `research` is what CI installs

uv run ruff check src/ tests/ examples/   # lint (the release gate)
uv run mypy                               # strict type checking
uv run pytest -q                          # coverage >= 90% AND zero warnings

Without the research extra numpy is missing, futures/ will not import, and your local run silently diverges from CI.

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, and tests/integration/test_mcp_protocol.py speaks the real MCP handshake over stdio.

Two gates surprise people. tests/test_consistency.py fails the build when the docs stop describing the product — version lockstep, tool counts (total and per section), and the declared scope. filterwarnings = ["error"] means any new warning is a build failure; the existing ignores name their upstream cause. 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

See ROADMAP.md for the full three-phase programme and its measured state.

• Migrate to MCP SDK 2.x — done, mcp[cli]==2.3.0.
• Exchange surfaces beyond spot — futures research shipped (read-only, offline). Futures execution is deliberately out of scope: see SECURITY.md.
• 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/.

The futures engine holds itself to the same bar, plus corrections for multiple testing (Deflated Sharpe Ratio, probability of backtest overfitting) — because the more configurations you try, the more certain you are to find beautiful noise.

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 Krmaazha. Part of Krmaazha's MCP product line.

License

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

_{mcp-name: io.github.KumailQazi/krmaazha-binance-mcp}