# Binance MCP Server — Railway / USDⓈ-M Futures Edition

MCP server for Binance USDⓈ-M Futures public market data.

## Why this version is different

The original project used Binance Spot REST (`api.binance.com`) and legacy
WebSocket URLs. That is a poor fit for a Railway deployment that receives
HTTP 451 from Binance.

This version uses Binance's current USDⓈ-M Futures WebSocket architecture:

- Market data: `wss://fstream.binance.com/market`
- High-frequency public depth: `wss://fstream.binance.com/public`

The server maintains an in-memory live cache and exposes MCP tools over
Streamable HTTP.

## Important limitation

This build intentionally does **not** depend on Binance REST for live public
data.

Therefore:

- `get_price`, `get_24hr_ticker`, `get_order_book`, `get_book_ticker`,
  `get_recent_trades`, and `get_aggregate_trades` are live WebSocket-backed.
- `get_recent_trades` means trades received since the collector connected.
- The order book is a top-5/10/20 **partial** depth stream, not a full local
  order-book reconstruction.
- `get_historical_prices` currently exposes the rolling 1-minute live kline
  cache, not arbitrary historical Binance candles.
- Historical REST-only tools return a clear error instead of silently failing.

## Railway

Build:

```text
docker build .
```

Start:

```text
python run_server.py
```

Railway should expose the MCP endpoint at:

```text
https://YOUR-DOMAIN/mcp
```

The server reads Railway's `PORT` environment variable automatically.

## Recommended Spark test

Ask Gemini Spark:

> Using the Binance MCP, analyze BTCUSDT Futures right now. Call
> get_price, get_24hr_ticker, get_order_book(depth=10),
> get_recent_trades(limit=20), get_book_ticker, and
> subscribe_to_trade_stream. Report exactly which tools succeeded and show
> the returned market data.

The first call may take a few seconds while the WebSocket collectors connect.

## Source architecture

```text
Gemini Spark
    |
    v
Railway MCP /mcp
    |
    +--> Market WS
    |      wss://fstream.binance.com/market/stream
    |      ticker + aggTrade + bookTicker + kline_1m
    |
    +--> Public Depth WS
           wss://fstream.binance.com/public/ws/<symbol>@depth20@100ms
```