# microstructure-mcp

**Market-microstructure primitives for AI agents, over MCP.**

LLM trading agents are usually fed raw candles and asked to "figure out the chart". This server does the deterministic part for them: it computes structured market-structure features — liquidity zones, fair value gaps, order blocks, break of structure — from live exchange data and exposes them as typed [MCP](https://modelcontextprotocol.io) tools. The agent reasons; the server measures.

Works out of the box with Claude Desktop, Claude Code, and any MCP-compatible client. Data source: Bybit v5 public API (no API key required).

## Tools

| Tool | What it returns |
|---|---|
| `get_liquidity_zones` | Clusters of equal highs/lows (buy-side / sell-side resting liquidity), touch count, swept status, distance from price |
| `get_fair_value_gaps` | 3-candle FVGs with zone boundaries, size %, filled / mitigated status |
| `get_order_blocks` | Last opposite candle before an impulsive move, with mitigation status |
| `get_market_structure` | Current trend read + recent BOS / CHoCH events |
| `get_snapshot` | Everything above in a single call — the cheapest way to give an agent full context |

All tools take `symbol` (e.g. `BTCUSDT`), `timeframe` (`1m`–`1w`) and `limit`, plus per-tool sensitivity parameters. Output is compact JSON designed to be token-efficient in agent context windows.

## Quick start

```bash
git clone https://github.com/rustamovppl/microstructure-mcp
cd microstructure-mcp
pip install -e .
```

Add to Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "microstructure": {
      "command": "microstructure-mcp"
    }
  }
}
```

Then ask the agent something like: *"Pull a 4h snapshot of BTCUSDT and describe where liquidity is resting relative to the current structure."*

## Example output

`get_liquidity_zones("BTCUSDT", "4h")` →

```json
{
  "symbol": "BTCUSDT",
  "timeframe": "4h",
  "last_close": 96420.5,
  "zones": [
    {
      "side": "buy_side",
      "level": 97180.0,
      "touches": 3,
      "swept": false,
      "distance_pct": 0.7877
    }
  ]
}
```

## Detection logic (brief)

- **Swings** — symmetric fractal window (`lookback` candles each side).
- **Liquidity zones** — swing highs/lows clustered within `tolerance_pct`; ≥ `min_touches` equal highs = buy-side liquidity, equal lows = sell-side. Marked `swept` once traded through.
- **FVG** — classic 3-candle gap; tracked to `mitigated` (price entered the zone) or `filled` (traded through it).
- **Order blocks** — last opposite-direction candle preceding a move ≥ `impulse_pct` within `impulse_window` candles.
- **Structure** — close beyond the last confirmed swing = BOS; against prevailing direction = CHoCH.

The logic is pure-Python, dependency-light, and unit-tested (`pytest tests/`).

## Roadmap

- [ ] Multi-timeframe confluence in `get_snapshot`
- [ ] Volume-weighted liquidity scoring
- [ ] Additional data sources (Binance, Hyperliquid)
- [ ] SSE transport for hosted deployment
- [ ] Backtest harness for detection-parameter tuning

## Disclaimer

This server produces **descriptive market-structure features, not trade signals**. Nothing here is financial advice; markets can and will invalidate any structural read.

## License

MIT