# binance-market-mcp-server

An MCP (Model Context Protocol) server that gives Claude live and historical
Bitcoin (or any Binance pair) market data — the data layer for a
regime-switching DCA signal system. It does not compute momentum, EGARCH,
or any signal logic itself; it fetches clean price data, and the analysis
happens downstream in the skill/prompt that consumes it.

## What it exposes

Two tools, backed by Binance's free public REST API (no key or signup
required):

### `binance_get_current_price`
Live snapshot: last price, 24h change (absolute + %), 24h high/low, 24h
volume. Defaults to `BTCUSDT` but accepts any Binance pair.

### `binance_get_historical_ohlc`
Historical daily/hourly/weekly OHLC candles for a date range. Handles
pagination transparently past Binance's 1000-candle-per-request cap (returns
up to 2,000 candles per call; narrow the date range if you need more).
Binance's `BTCUSDT` history begins **2017-08-17** — covers the 2020 and 2024
halving cycles in full, most of the 2017–2018 cycle.

Both tools are read-only (no orders, no account access — this hits Binance's
public market-data endpoints only, nothing that requires an API key).

## Why Binance and not CoinGecko

CoinGecko's free Demo tier only gives ~1 year of historical daily data —
not enough for multi-year cycle backtesting. Binance's public klines
endpoint gives free, keyless access to daily candles back to 2017, which is
what a 4+ year DCA horizon backtest actually needs.

## Project structure

```
binance-market-mcp-server/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # entry point, stdio + HTTP transport
│   ├── types.ts              # shared TS interfaces
│   ├── constants.ts          # API base URL, limits, defaults
│   ├── tools/market.ts       # tool registration + handlers
│   ├── services/binance-client.ts  # Binance API client, pagination, errors
│   └── schemas/market.ts     # Zod input validation
└── dist/                     # compiled output (after `npm run build`)
```

## Local development

```bash
npm install
npm run build

# stdio mode (for Claude Desktop / Claude Code local config)
npm start

# HTTP mode (for remote/claude.ai custom connector)
TRANSPORT=http PORT=3000 npm start
```

Quick manual test once running in HTTP mode:

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
```

You should get back a `serverInfo` block confirming the handshake. This part
was verified in the build sandbox. **What was NOT verified in the sandbox:
actual live calls to the Binance API** (the sandbox's network whitelist
doesn't include api.binance.com). First real end-to-end test — an actual
`binance_get_current_price` call hitting live Binance — needs to happen
either locally on your machine or after deployment. Do this before trusting
the server for anything real.

## Deploying for claude.ai (Option B — remote HTTP)

Any Node-friendly host with a free tier works. Two straightforward options:

### Render (recommended — simplest free tier for this)
1. Push this folder to a GitHub repo.
2. On [render.com](https://render.com): New → Web Service → connect the repo.
3. Build command: `npm install && npm run build`
4. Start command: `npm start`
5. Add environment variable: `TRANSPORT=http` (Render sets `PORT` itself).
6. Deploy. Your MCP endpoint will be `https://<your-app>.onrender.com/mcp`.

Note: Render's free tier spins down after inactivity — first request after
idle will be slow (cold start, ~30-50s). Fine for a weekly manual check-in,
not for anything latency-sensitive.

### Railway
Same idea — connect repo, set `TRANSPORT=http`, Railway auto-detects Node
and runs `npm run build && npm start`. Railway's free tier has usage-hour
limits rather than spin-down; check current limits before committing to it
long-term.

### Connecting in claude.ai
Settings → Connectors → Add custom connector → paste your deployed
`/mcp` URL. No authentication is configured on this server (it's read-only
public market data) — if you want to restrict access, add an API-key check
in `src/index.ts` before connecting it to anything shared.

## Extending later

- **Whale wallet / on-chain data**: not covered by this server. Flagged
  earlier as a free-tier data gap — needs a separate connector once that
  source is picked.
- **Other symbols**: already generalized — `symbol` param works for any
  Binance pair, not just BTCUSDT.
- **Rate limits**: Binance public endpoints allow generous request volume
  for this use case (weekly checks + occasional backtest pulls). No API key
  needed. If you scale this to many symbols/high frequency, revisit.