Binance MCP

A security-first Model Context Protocol server for Binance.

It provides a compact surface instead of mirroring hundreds of Binance endpoints as individual MCP tools:

• binance_public_request — GET any public Spot, USDⓈ-M Futures, COIN-M Futures, Options, or Portfolio Margin REST path.

• binance_account_request — signed GET-only account access using credentials stored on the server.

• binance_order_request — standard create/cancel Spot, Futures, and Options order operations, disabled unless the deployment explicitly enables trading.

• binance_simple_earn_subscribe — subscribe Spot/Funding funds into a specified Simple Earn Flexible product.

• binance_simple_earn_redeem — redeem a specified Simple Earn Flexible amount to Spot or Funding.

• binance_dual_investment_subscribe — subscribe Spot funds into one exact Dual Investment product after live product revalidation and optional quote guards.

• binance_dual_investment_positions — read normalized Dual Investment positions.

• binance_dual_investment_from_flexible_earn — guarded orchestration from Flexible Earn → Spot → one exact Dual Investment product while preserving a configured Earn balance.

• binance_auth_status — redacted capability status. It never returns secrets.

The generic public request tool keeps pace with Binance adding new market-data endpoints without forcing a new MCP schema for every endpoint. Financial writes deliberately do not use a generic signed POST tool: each supported write is a named, purpose-specific action.

Security model

There are two independent authentication boundaries:

1. MCP client → Binance MCP uses the owner-approved OAuth model from the NsTut MCP stack: authorization code flow, PKCE S256, dynamic client registration, short-lived access tokens, rotating refresh tokens, persisted hashed grants, strict redirect validation, and fail-closed MCP access.

2. Binance MCP → Binance uses a Binance API key plus HMAC secret, Ed25519 private key, or RSA private key. Credentials, signatures, and private keys stay server-side and are never returned by tools.

Binance Login OAuth2 is not used for ordinary self-hosting because Binance currently limits that program to approved ecosystem partners. If Binance broadens access later, it can be added as another credential provider without changing the MCP OAuth boundary.

Safe defaults

• MCP refuses protected requests when OAuth is not configured.

• Generic account access is GET-only.

• Trading and financial writes are disabled unless BINANCE_TRADING_ENABLED=true is set by the deployment owner.

• Withdrawals are intentionally unsupported.

• Full URLs are rejected. Requests are pinned to known Binance API hosts.

• recvWindow defaults to 5000 ms and may not exceed 60000 ms.

• Boolean query parameters are normalized to Binance-compatible lowercase true / false before encoding and signing.

• Non-ASCII request parameters are percent-encoded before signing, matching current Binance signed-endpoint requirements.

• Dual Investment auto-compounding defaults to NONE; Standard or Advanced compounding is never silently enabled.

• Dual Investment writes re-fetch the exact product before subscribing and can enforce minimumApr and minimumStrikeDistancePercent.

• The Earn → Dual Investment orchestration supports preserveEarnAmount and refuses to redeem funds that would push the remaining Flexible Earn balance below that floor.

• After redemption, the orchestration re-fetches the exact product and re-runs quote guards. If the product disappears or a guard fails, it leaves the redeemed funds in Spot and does not substitute another product.

• Secret/key files are excluded by .gitignore and .dockerignore.

For account keys, prefer a dedicated Binance API key with only the permissions you need and IP restrictions where practical. Binance recommends Ed25519 keys for performance and security.

Related MCP server: binance-mcp

Supported API hosts

Portfolio Margin reads use product = portfolio_margin. Its UM, CM, and margin order families use different paths, so they are deliberately not collapsed into the standard binance_order_request tool.

Example public call:

product = spot
path = /api/v3/ticker/price
params = {"symbol":"BTCUSDT"}

Example account call:

product = spot
path = /api/v3/account
params = {"omitZeroBalances":true}

Financial write tools

These actions can move funds. They all require BINANCE_TRADING_ENABLED=true and a Binance API key with the permissions required by Binance.

Subscribe Simple Earn Flexible

binance_simple_earn_subscribe accepts a Flexible Earn productId, a positive decimal amount, optional autoSubscribe (default true), and optional sourceAccount (SPOT, FUND, or ALL; default SPOT).

Redeem Simple Earn Flexible

binance_simple_earn_redeem accepts a Flexible Earn productId, a positive decimal amount, and an optional destAccount. The default destination is SPOT.

Subscribe Dual Investment

binance_dual_investment_subscribe accepts the exact product id plus the explicit investment pair and direction (investCoin, exercisedCoin, optionType). The server re-fetches the live product and obtains the Binance orderId itself, preventing callers from supplying stale or arbitrary order ids.

Optional quote guards:

• minimumApr: decimal APR floor, e.g. 0.18 means 18%.

• minimumStrikeDistancePercent: minimum live distance between spot and strike, e.g. 2.0.

• autoCompoundPlan: defaults to NONE; STANDARD or ADVANCED are accepted only when the selected live product advertises that plan.

Read Dual Investment positions

binance_dual_investment_positions wraps Binance's signed position endpoint and normalizes position/order id, available product id, invest/exercised assets, deposit amount, strike, APR, settlement date, purchase status, direction, and auto-compound plan.

Flexible Earn → Dual Investment orchestration

binance_dual_investment_from_flexible_earn is the preferred user-facing workflow when the source funds are in Simple Earn Flexible:

1. Read the exact Flexible Earn position.

2. Confirm it is redeemable and the requested amount is available.

3. Enforce preserveEarnAmount.

4. Fetch and validate the exact Dual Investment product and optional quote guards.

5. Record the Spot free balance.

6. Redeem the requested amount to Spot.

7. Verify Spot received the funds.

8. Re-fetch the exact Dual Investment product and re-run all guards.

9. Subscribe only if the same product still passes.

10. Read positions and verify the resulting subscription.

If the product becomes unavailable or fails a guard after redemption, the workflow returns a partial-completion result with subscribed=false and leaves the funds in Spot. It does not automatically choose a substitute product or re-subscribe the funds to Simple Earn.

Configuration

Copy .env.example and provide the MCP OAuth values. For Binance account access, configure BINANCE_API_KEY and one signer:

• BINANCE_API_SECRET for HMAC, or

• BINANCE_PRIVATE_KEY_PATH for Ed25519/RSA PEM, optionally with BINANCE_PRIVATE_KEY_PASSPHRASE.

Set BINANCE_TRADING_ENABLED=true only on deployments where named financial write tools should be enabled.

Do not paste Binance credentials into a chat conversation or commit them to Git.

Local run

python -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
pytest
uvicorn main:app --host 127.0.0.1 --port 8080

The MCP endpoint is /mcp/; health is /health.

Docker

docker build -t binance-mcp .
docker run --rm -p 8080:8080 --env-file .env binance-mcp

Mount /app/data persistently so OAuth grants survive container replacement. If using an asymmetric Binance key, mount the private key read-only and point BINANCE_PRIVATE_KEY_PATH at it.

CI/CD

This public repository intentionally contains no GitHub Actions workflows and no production deployment configuration. NsTut's CI/CD lives in the private UpperMoon0/NsTut-CICD repository so deployment credentials, runner policy, and infrastructure topology stay outside the public source tree.

Scope

The public reader intentionally exposes REST GET endpoints rather than WebSocket streams. Account User Data Streams can be added later as bounded MCP resources if a concrete use case needs event streaming.

This project is not affiliated with or endorsed by Binance.