Skip to main content
Glama
microstructure-mcp

microstructure-mcp

by Rustamovppl

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.

Related MCP server: Bybit MCP Server

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

Available Tools

5 tools
get_fair_value_gapsC

Detect 3-candle fair value gaps (FVG) with fill/mitigation status.

Inputs: symbol (required), limit, timeframe, min_gap_pct, +1 more. Returns: result

get_liquidity_zonesB

Detect resting-liquidity levels (clusters of equal highs = buy-side, equal lows = sell-side).

Returns levels sorted by distance from current price, with touch count and whether the level has already been swept.

Inputs: symbol (required), limit, timeframe, min_touches, +1 more. Returns: result

get_market_structureC

Current trend read plus recent break-of-structure (BOS) and change-of-character (CHoCH) events.

Inputs: symbol (required), limit, timeframe. Returns: result

get_order_blocksC

Detect order blocks: the last opposite candle before an impulsive move, with mitigation status.

Inputs: symbol (required), limit, timeframe, impulse_pct. Returns: result

get_snapshotB

One-call snapshot: structure + nearest liquidity + unfilled FVGs + recent order blocks.

Inputs: symbol (required), limit, timeframe. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct microstructure concept (FVG, liquidity zones, market structure, order blocks) with clear, non-overlapping descriptions. The snapshot tool aggregates others but serves a different convenience purpose.

    Naming Consistency5/5

    All tools follow a consistent 'get_' prefix pattern with descriptive noun phrases (fair_value_gaps, liquidity_zones, etc.), making it easy to predict tool behavior from names.

    Tool Count5/5

    With only 5 tools, the server is tightly scoped to essential microstructure analysis concepts. Each tool earns its place, and the count is ideal for this specialized domain.

    Completeness5/5

    The set covers the core microstructure concepts (FVG, liquidity, market structure, order blocks) and adds a snapshot tool for convenience. There are no obvious gaps for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible AI clients to access live crypto market data and AI-driven quantitative analysis, with structured outputs and full observability.
      -
    • A
      license
      C
      quality
      B
      maintenance
      A production-ready MCP server for Bybit — 206 tools covering market data, trading, positions, account management, assets, and real-time WebSocket streams. Enables AI assistants to interact directly with the Bybit cryptocurrency exchange through natural language.
      400
      1,625 npm
      45
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables fetching live crypto market data from Binance, Bybit, and Hyperliquid via MCP tools, including klines, orderbook, funding rates, technical indicators, and market breadth for real-time analysis by LLMs.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to analyze smart-money market structure—trend, character shifts (ChoCh/BOS), liquidity sweeps, fair value gaps, order blocks, and pullback zones—from Hyperliquid or user-supplied candles.
      3
      Apache 2.0