mcpField
P
perpwatch

perpwatch

Local
github.com/CloudCorpRecordsFinance0Updated 1w ago
Repository

About perpwatch

perpwatch is a forwarding client for the MarketTrace perpetual-futures microstructure feed, aimed at users examining crypto market conditions and trading flows. It validates calls locally and proxies eleven read-only tools to an endpoint aggregating Binance, Bybit, OKX and Hyperliquid data.

Key features

  1. 01Funding, open interest and market snapshots
  2. 02Conditional outcomes and state history
  3. 03Liquidations, volume profiles and big trades
  4. 04Footprint events and stacked imbalances
  5. 05Local symbol validation and CLI

Use cases

  1. 01Review funding and open interest for a supported symbol
  2. 02Explore historical market states and conditional returns
  3. 03Inspect recent liquidations and large trades
  4. 04Examine volume profiles and order-book footprint events

MCP support

It exposes eleven read-only tools through a stdio MCP server and forwards calls to the hosted MarketTrace endpoint. Data requests require the `MARKETTRACE_BEARER` bearer token.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "cloudcorprecords-perpwatch": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/perpwatch"
      ]
    }
  }
}
Run commandnpx -y @reneturcios/perpwatch

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@reneturcios/perpwatch0.1.0
ocighcr.io/cloudcorprecords/perpwatch:0.1.0

Tools

11

Saved tool list · updated 1w ago

ParameterTypeRequiredDescription
symbolstringYesAsset symbol: BTC, ETH, SOL, BNB, XRP, DOGE, HYPE, ZEC or ENA (case-insensitive; a `USDT` suffix is accepted, e.g. `BTCUSDT`).

Details

From the project README

perpwatch

A forwarding client for the MarketTrace perpetual-futures microstructure feed. perpwatch exposes the feed's eleven read-only tools as a stdio MCP server (and a small CLI): it validates each call locally — including the nine-symbol universe (BTC, ETH, SOL, BNB, XRP, DOGE, HYPE, ZEC, ENA, case-insensitive with an optional USDT suffix) — and proxies the call to the hosted endpoint, which aggregates Binance, Bybit, OKX and Hyperliquid.

Tools, by the question they answer:

  • Market context — get_market_state (one normalized snapshot: funding + percentile, OI, volume, CVD, book imbalance, liquidation pressure, basis), get_funding_percentile
  • History and base rates — get_conditional_outcomes (measured forward returns after a stated condition; history_silent when the evidence is too thin), get_state_history (15-minute state archive series), get_ohlcv (consolidated candles)
  • Flow and footprint — get_liquidations_recent, get_volume_profile (POC / value area / naked POCs), get_big_trades, get_footprint_events (absorbed / pulled book walls), get_stacked_imbalances
  • help — the tool guide, served locally with no credentials: tools grouped by question, example calls, scales, and limits.

Auth

The hosted endpoint uses OAuth sign-in (browser → email magic link). Complete that sign-in and export the resulting bearer:

export MARKETTRACE_BEARER="<bearer from the hosted sign-in>"

Without it, data calls fail with an error naming MARKETTRACE_BEARER and the sign-in — no data is fabricated. The endpoint defaults to https://api.markettrace.ai/mcp; override it with MARKETTRACE_MCP_URL. Market data is informational only, not financial advice.

CLI

npx @reneturcios/perpwatch tools
npx @reneturcios/perpwatch help
npx @reneturcios/perpwatch call get_market_state '{"symbol":"BTC"}'
npx @reneturcios/perpwatch --version

Exit codes: 0 success, 1 runtime error (including a missing bearer or an upstream error), 2 usage error.

MCP server

npx -y @reneturcios/perpwatch mcp

MCP client config:

{
  "mcpServers": {
    "perpwatch": {
      "command": "npx",
      "args": ["-y", "@reneturcios/perpwatch", "mcp"],
      "env": { "MARKETTRACE_BEARER": "<bearer from the hosted sign-in>" }
    }
  }
}

Docker

docker run -i -e MARKETTRACE_BEARER="<bearer>" ghcr.io/cloudcorprecords/perpwatch

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.