Binance MCP Server (amazing-binance-mcp)

A Model Context Protocol server for the Binance Spot + Wallet REST API, built on the official MCP Python SDK (FastMCP, stdio transport). It authenticates with a plain API key — Ed25519 or HMAC, no OAuth — so an LLM can read your deposits, withdrawals, trades, balances, fiat and Pay history and live market data, and — only when you flip the kill-switch — place and cancel spot orders, order lists, TWAP algo orders and conversions.

The PyPI distribution and console script are both amazing-binance-mcp (the bare binance-mcp and binance-mcp-server names on PyPI belong to unrelated packages). Always run uvx amazing-binance-mcp.

Safety model

Three rails, all enforced in the HTTP client — not in the tools — so no tool can forget them:

• No withdrawals, ever. There is no withdrawal tool, and the client refuses the withdrawal and fiat-rail endpoints under any configuration. Create the API key with "Enable Withdrawals" off and an IP allowlist as well; binance_health_check warns if the key can withdraw.
• Trading is off by default. Anything that moves funds or changes account state — orders, cancels, order lists, transfers between your wallets, convert, TWAP, dust conversion — returns Error: … trading is disabled until BINANCE_ALLOW_TRADING=1. The order dry-run (binance_test_order) always works. Those tools are marked 🔒 below.
• Confirmations never claim more than Binance said. A placed order echoes the status Binance returned (an EXPIRED FOK is reported as not live); a TWAP is accepted, not executed; a convert is converted only when the status is SUCCESS. A 5xx or timeout on a mutating call is reported as execution UNKNOWN with the tool to query before retrying — the server never retries a mutation on its own.

Everything else is read-only and works with a key that only has "Enable Reading".

Features

• Your whole history, since the account was created. Deposits, withdrawals, fiat orders and payments, Binance Pay, convert trades and — per symbol, since Binance has no cross-symbol endpoint — every spot trade, via budgeted walk tools that slice the 90-day / 30-day / 24-hour windows the API imposes and hand you a resume cursor when a budget runs out (see History walks).
• Spot trading for algotrading. Dry-run validation, market/limit/stop orders, cancel and cancel-replace, OCO / OTO / OTOCO lists, TWAP algo orders, convert quotes — numbers travel as strings exactly as you typed them, and every per-type mandatory parameter set is validated locally before anything is signed.
• Market data without a key. Exchange info with the filters an order must respect, order book, trades, klines, tickers.
• Spot, funding and earn balances, wallet-to-wallet transfers, dust, fees, dividends, and the account's API-key permissions.
• Dual-format responses — markdown for humans and LLMs (default) or JSON for programmatic use, per call via response_format.
• Strict inputs, uniform errors. One pydantic model per tool (extra="forbid"), and Binance's {code, msg} errors normalised into readable strings with a hint for the codes that have a known fix (-1021 clock drift, -1022 signature, -2015 permissions/IP, -2010 filters, -1127 window too wide …).
• stdio-only transport. No HTTP/SSE and no logging to stdout — stdout is the protocol channel.

Available Tools

All 83 tools, grouped by module. 🔒 = refused unless BINANCE_ALLOW_TRADING=1.

Read tools return markdown (default) or JSON; mutating tools return a confirmation that echoes exactly what Binance returned.

Prerequisites

• uv — for the zero-install uvx path and for local development (Python 3.13+ is only needed for the clone path; uvx brings its own).
• A Binance API key. Binance → Account → API Management:
  1. Choose Self-generated and paste an Ed25519 public key (recommended — Binance has deprecated HMAC keys, and an unrestricted HMAC key may only hold "Enable Reading"). Generate the pair locally and keep the private key out of the repo:

     openssl genpkey -algorithm ed25519 -out ~/.config/binance/ed25519.pem
     openssl pkey -pubout -in ~/.config/binance/ed25519.pem     # paste this one into Binance
     

     A "System generated" HMAC key (key + secret) also works.
  2. Permissions: Enable Reading on; Enable Spot & Margin Trading only if you will place orders; Enable Withdrawals off; Permits Universal Transfer only if you want binance_transfer_between_wallets.
  3. Restrict access to trusted IPs — the IP of the machine that runs this server.
• (Optional) Spot testnet keys from https://testnet.binance.vision to exercise the trading tools with virtual funds. The testnet serves only /api/v3 (market data, account, orders) — wallet, fiat, Pay, convert and algo tools return 404 there.
• (Optional) Docker if you prefer the container path.

Quickstart

git clone https://github.com/trustxai/binance-mcp.git
cd binance-mcp
uv sync --group dev
cp .env.example .env          # set BINANCE_API_KEY and BINANCE_PRIVATE_KEY_PATH (or BINANCE_API_SECRET)
uv run amazing-binance-mcp    # starts the stdio server

The server speaks MCP over stdio, so it is normally launched by an MCP client (see Client Configuration) rather than run by hand. Call binance_health_check first: it reports connectivity, clock drift against Binance's server time, and the key's permission flags — with a ⚠️ if withdrawals are enabled or the key has no IP allowlist.

Run with uvx (zero install)

BINANCE_API_KEY=your_key BINANCE_PRIVATE_KEY_PATH=~/.config/binance/ed25519.pem uvx amazing-binance-mcp

Public market data needs no credentials at all: uvx amazing-binance-mcp with nothing set serves the market-data and health tools.

Use amazing-binance-mcp, not binance-mcp. The bare name on PyPI is an unrelated package and will not run this server.

Client Configuration

Every client launches the server as a subprocess and passes credentials through env. Replace your_key and the PEM path; for an HMAC key use BINANCE_API_SECRET instead of BINANCE_PRIVATE_KEY_PATH. Add "BINANCE_ALLOW_TRADING": "1" only for a client you want to be able to trade.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "binance": {
      "command": "uvx",
      "args": ["amazing-binance-mcp"],
      "env": {
        "BINANCE_API_KEY": "your_key",
        "BINANCE_PRIVATE_KEY_PATH": "/Users/you/.config/binance/ed25519.pem"
      }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config; on macOS it lives at ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "binance": {
      "command": "uvx",
      "args": ["amazing-binance-mcp"],
      "env": {
        "BINANCE_API_KEY": "your_key",
        "BINANCE_PRIVATE_KEY_PATH": "/Users/you/.config/binance/ed25519.pem"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add binance \
  --env BINANCE_API_KEY=your_key \
  --env BINANCE_PRIVATE_KEY_PATH=$HOME/.config/binance/ed25519.pem \
  -- uvx amazing-binance-mcp

Or add the equivalent block to ~/.claude.json under mcpServers (same shape as the Cursor example above).

MCP Inspector

BINANCE_API_KEY=your_key BINANCE_PRIVATE_KEY_PATH=~/.config/binance/ed25519.pem \
  npx @modelcontextprotocol/inspector uvx amazing-binance-mcp

If you cloned the repo, uv run mcp dev src/binance_mcp/server.py does the same (the mcp dev CLI ships in the dev dependency group).

Docker

Build the image from the repo Dockerfile, then point any client at docker run. The PEM has to be mounted into the container; with an HMAC key you can pass the secret through env instead and drop the volume.

docker build -t amazing-binance-mcp .

{
  "mcpServers": {
    "binance": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/you/.config/binance/ed25519.pem:/keys/ed25519.pem:ro",
        "-e", "BINANCE_API_KEY",
        "-e", "BINANCE_PRIVATE_KEY_PATH",
        "amazing-binance-mcp"
      ],
      "env": {
        "BINANCE_API_KEY": "your_key",
        "BINANCE_PRIVATE_KEY_PATH": "/keys/ed25519.pem"
      }
    }
  }
}

The -i flag is required — the server communicates over stdin/stdout.

Authentication

Every signed request carries the key in the X-MBX-APIKEY header plus a timestamp, a recvWindow and a signature over the query string:

• Ed25519 key (recommended): the private key PEM at BINANCE_PRIVATE_KEY_PATH (optionally encrypted — BINANCE_PRIVATE_KEY_PASSPHRASE) signs the payload; the signature is base64 and percent-encoded, as Binance requires. RSA PEMs work the same way.
• HMAC key: BINANCE_API_SECRET produces the HMAC-SHA256 hex signature. Supported, but Binance has deprecated HMAC keys.

The key is never logged or echoed. Missing credentials fail lazily at the first signed request with a clear message; public market data never needs them. The signing code is unit-tested against the example vectors Binance publishes in its own documentation.

Environment Variables

Enabling trading

1. Give the key Enable Spot & Margin Trading (and an IP allowlist).
2. Set BINANCE_ALLOW_TRADING=1 in that client's env — and only there.
3. Validate with binance_test_order first: it runs Binance's filter checks (lot size, price filter, notional) without touching the book. binance_get_exchange_info shows the filters for a symbol.

Start on the testnet: BINANCE_TESTNET=1 with keys from https://testnet.binance.vision lets you place, query and cancel orders with virtual funds. The suite's own trading smoke test refuses to run anywhere but the testnet.

History walks

Binance caps history queries per call — deposits/withdrawals and Pay at 90 days, convert at 30, spot trades and orders at 24 hours when you pass a time range — and myTrades needs a symbol. The binance_get_all_* and *_history tools walk those windows newest-first from until (default now) down to since, within a call budget sized to the endpoint's weight (withdraw history costs 18 000 UID weight per call, so its default budget is 10 calls; deposits cost 1 and get 60).

When a budget runs out before since, the response says so and returns resume_before — the boundary of the next unfetched range. Call the tool again with the same since and that resume_before to continue; rows are deduplicated by id, so an overlap is harmless. If the budget could not finish even the newest window the tool says so explicitly instead of handing you a cursor that would repeat the same calls.

binance_get_all_my_trades first discovers which symbols you may have traded (assets you hold or held, crossed with the exchange's symbol list — Binance has no endpoint for this) and walks each one with fromId; it returns a cursor of the last trade id per symbol that you can paste back for incremental runs.

What is not available

• Binance Card spending. Binance exposes no API for card transactions. The closest reads are binance_get_funding_wallet (the wallet behind Pay/Card), Pay transactions with walletType 4/6, and spot⇄funding transfer history.
• Withdrawals, by design — use the Binance app.
• Futures, margin trading, sub-accounts — out of scope for this server.

Running Manually

uv run amazing-binance-mcp     # console script (recommended)
uv run python -m binance_mcp    # module entry point

Troubleshooting

• -1021 Timestamp for this request is outside of the recvWindow. Your clock drifts from Binance's. binance_health_check prints the drift; sync the clock (NTP) or raise BINANCE_RECV_WINDOW_MS.
• -1022 Signature for this request is not valid. The secret does not match the key, or the key type is wrong (an HMAC secret with a self-generated key, or vice versa).
• -2015 Invalid API-key, IP, or permissions for action. The key lacks the permission the tool needs (Reading, Spot & Margin Trading, Permits Universal Transfer), or this machine's IP is not on the key's allowlist.
• Error: … trading is disabled. Expected: set BINANCE_ALLOW_TRADING=1 for the client that should trade. The dry-run binance_test_order never needs it.
• -1127 / "window too wide". You passed a time range wider than the endpoint allows (24 h for trades/orders, 90 d for deposits/withdrawals/Pay, 30 d for convert). Narrow it, or use the walk tool for that history.
• 429, 418, or "used weight" warnings. /api calls share a 6000-weight-per-minute budget per IP; /sapi has separate per-IP and per-UID budgets. Heavy tools say so in their descriptions (account snapshot 2400, fiat orders 45 000 UID, withdraw history 18 000 UID). Back off; a 418 is a temporary IP ban.
• 404 on wallet/fiat/Pay/convert/algo tools. You are on the testnet, which serves only /api/v3. Those tools need the real API with a read-only key.
• 1 validation error for …Arguments when calling a tool by hand. Every tool takes a single params object: {"params": {"symbol": "BTCUSDT"}}, not the bare fields. MCP clients read that from the schema; scripts and the Inspector must nest it.
• uvx binance-mcp runs the wrong thing. This server is amazing-binance-mcp.
• "Why is my card spend missing?" See What is not available.

Contributing

Conventional Commits drive releases (release-please). Before pushing, run the full gate — it must exit 0:

uv run pytest -m "not live and not trading" && uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/ && uv run mypy src/

Live smokes run with a read-only key in .env (uv run pytest -m live); the trading smoke needs BINANCE_TESTNET=1 BINANCE_TEST_ALLOW_TRADING=1 and testnet keys. Regenerate the tool table with uv run python scripts/gen_tool_table.py --write.

License

Apache-2.0