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 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

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

Add to Claude Desktop (claude_desktop_config.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") →

{
  "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