Plumbline: DeepBook Market Data

Plumbline: read-only DeepBook v3 market data for AI agents

[npm] [Smithery] [MCP] [License: MIT]

Plumbline is a free, read-only Model Context Protocol server for Sui DeepBook v3 market data. It gives agents pools, mid price and spread, order book depth, volume, live on-chain fees, recent trades and OHLCV candles.

• No API keys, no wallet, no signing, no trading. Every tool is annotated readOnlyHint: true.
• Small outputs. Compact JSON with column/row arrays for series and sensible rounding.
• Fast and polite. An in-memory TTL cache (2 s for books, up to 10 min for metadata), de-duplicated requests and 8 s timeouts.

Disclaimer: for education and information only. This is not financial, investment, legal or tax advice. Data comes from public third-party sources (the Mysten Labs DeepBook indexer and Sui GraphQL). It may be delayed, incomplete or wrong, and is provided "as is" without warranty. Nothing here recommends buying, selling or holding any asset.

Quickstart

npx -y plumbline-mcp

The server runs over stdio and needs Node.js 18.17 or later. It needs no configuration.

Claude Code

claude mcp add plumbline -- npx -y plumbline-mcp

Claude Desktop, Cursor, Windsurf, VS Code or any stdio client

Add this to your client's MCP config (claude_desktop_config.json, ~/.cursor/mcp.json, and so on):

{  "mcpServers": {    "plumbline": {      "command": "npx",      "args": ["-y", "plumbline-mcp"]    }  }}

[Add to Cursor]

Smithery

npx -y @smithery/cli@latest mcp add nazarenechalice/plumbline --client claude   # or cursor, claude-code, vscode, windsurf, ...

You can also open the Smithery listing. For one-click Claude Desktop install, download the .mcpb bundle there.

Streamable HTTP (self-hosted)

npx -y plumbline-mcp --http --port 8081        # POST http://127.0.0.1:8081/mcp, GET /healthHOST=0.0.0.0 PORT=8081 npx -y plumbline-mcp --http

HTTP mode is stateless and returns JSON. It also serves a static server card at /.well-known/mcp/server-card.json and rate-limits each client to 120 requests per minute. Put it behind TLS before you expose it. Hosting notes are in deploy/DEPLOY.md.

Ask your agent

• "What's the spread on DeepBook SUI_USDC right now?"
• "How much liquidity is within 1% of mid on SUI_USDC?"
• "Show 1h candles for DEEP_USDC for the last day."
• "Which DeepBook pools had the most volume in the last 24 hours?"
• "What are the current taker and maker fees on SUI_USDC?"

The server also ships prompts (market_snapshot, compare_pools, liquidity_check) and resources (plumbline://guide, plumbline://disclaimer).

Tools

Pool names use BASE_QUOTE (for example SUI_USDC). Input is case-insensitive, and sui/usdc or SUI-USDC also work. An unknown pool returns a clear error with suggestions; USDC_SUI, for example, suggests SUI_USDC.

Example output (live, Oct 9 2026)

get_mid_price with {"pool":"SUI_USDC"}:

{"pool":"SUI_USDC","quote":"USDC","best_bid":1.0708,"best_ask":1.07106,"mid":1.07093,"spread":0.00026,"spread_bps":2.428,"last_price":1.0708,"as_of":"2026-10-09T08:38:03.997Z"}

One depth band from get_order_book (an earlier snapshot the same day):

{"pct":1,"bid_base":204536.4,"bid_quote":216152.61,"ask_base":105721.5,"ask_quote":113063.72,"bid_levels":26,"ask_levels":27}

get_pool_params with {"pool":"SUI_USDC"} (read live from the on-chain Pool object; trimmed):

{"pool":"SUI_USDC","source":"sui-onchain","taker_fee":{"pct":0.02,"bps":2},"maker_fee":{"pct":0,"bps":0},"stake_required_deep":100000,"tick":0.00001,"lot":0.1,"min_size":1}

get_ohlcv with {"pool":"SUI_USDC","interval":"1h","limit":2}:

{"pool":"SUI_USDC","interval":"1h","count":2,"cols":["open_time","open","high","low","close","volume_SUI"],"candles":[["2026-10-09T07:00:00Z",1.0658,1.07579,1.06268,1.07543,66001],["2026-10-09T08:00:00Z",1.07529,1.07817,1.06721,1.0708,26347.5]]}

Configuration (all optional)

How it compares

Plumbline only reads data. Trading MCPs for DeepBook build transactions and may hold keys. Broad Sui analytics MCPs cover many protocols. Plumbline goes deep on DeepBook market data: depth bands around mid, live on-chain fees, OHLCV and pool-name suggestions. You can give it to any agent without risk to funds.

Data sources: books, trades, volume and candles come from the public DeepBook indexer. Fees and pool parameters come from the live Pool object via Sui GraphQL.

Optional: pay-per-call (off by default)

Plumbline is free, and the stdio package is always free. A self-hosted HTTP operator can choose to meter calls, for example 100 free calls per day and then 0.002 USDC per call, paid in USDC on Sui. Metering is disabled unless PLUMBLINE_PAYMENTS=1 is set. The server is receive-only and never holds keys. The full design and security model are in docs/PAYMENTS.md.

Build from source

git clone https://github.com/SajanMelcher/plumbline-mcp.gitcd plumbline-mcpnpm install && npm run buildnode dist/index.js            # stdio; add --http for HTTP

Development

npm test            # live tests against the public indexer (SUI_USDC); needs networknpm run smoke       # spawns the server over stdio and calls every tool via the MCP clientnpm run smoke:http  # same over streamable HTTPnpm run inspector   # MCP Inspector UInpm run payments:testnet  # Sui testnet end-to-end with a throwaway payer (needs testnet SUI + USDC)npm run pack:mcpb   # MCPB bundle at build/plumbline.mcpb, validated with mcpb + a Smithery payload check (publishes nothing)

Notes and limits

• The public indexer serves at most about 100 price levels per side. When a depth band reaches past that, the response marks it truncated: true, and the value is a lower bound.
• list_pools parameters come from indexer metadata. get_pool_params reads the live on-chain Pool object, so it is authoritative when tick sizes or fees change through governance.
• Fees are DeepBook fixed-point values (1e9 scale), converted to pct and bps.
• No margin, balance-manager or wallet-specific endpoints are exposed.

Independence and name

Plumbline is named after a plumb line, the weighted cord used to measure depth and true vertical. Other candidates were Sounding and Tidemark. Plumbline is an independent community project. It is not affiliated with Mysten Labs, the Sui Foundation or DeepBook.

License

MIT. See LICENSE.