Skip to main content
Glama
Reservoir MCP

Reservoir MCP

by joshavenue

Reservoir MCP

Let your AI agent work with Reservoir, Hydromancer's free archive of Hyperliquid history, the same way the Exploring Reservoir guide does: DuckDB reading Parquet files straight from S3.

"How much was traded on xyz:ANT in its first 24 hours, and how many longs got liquidated?" "Show me hourly BTC candles for October 1." "What did the xyz:TSLA order book look like at 14:30 UTC yesterday? What would a $100K sell have cost?" "Who held the biggest positions in xyz:MSFT on October 20, and where are their liquidation prices?" "Which HIP-3 markets had the most liquidations last week?"

Your agent picks the tool, checks how much it will download, runs the query and explains the answer.

  • Everything in Reservoir: fills (trades, liquidations, ADL, builder and TWAP fills), 1-second candles, daily position, spot-balance and account-value snapshots, and 1-minute order books, for Hyperliquid and every HIP-3 venue (including ones that have shut down)

  • Same layout as the guide: same bucket paths, same market names, same DuckDB SQL. Anything the guide does, reservoir_query can run

  • Watches your AWS bill: Reservoir is requester pays. Every tool estimates the download first, stops above a limit you control, and reports what each call downloaded

  • Knows where Reservoir stops: for today's data, intraday positions, individual orders, funding, open-interest history or very large per-wallet scans, results point to the Hydromancer API endpoint that answers it directly

  • Read-only: it reads the Reservoir bucket and its own local copies. It cannot write elsewhere, trade, sign or touch funds

1. Set up AWS (once)

Reservoir is free, but downloads are billed to your own AWS account (requester pays). The first 100 GB a month of AWS internet transfer is free, then about $0.114 per GB. A typical question downloads a few MB to a few hundred MB.

  1. Install the AWS CLI v2.

  2. Sign in: aws login (or use a named profile with a read-only IAM user; see the guide for the policy).

  3. Check it works:

aws s3 ls s3://hydromancer-reservoir/ --request-payer requester --region ap-northeast-1

You also need uv, which runs the server.

Related MCP server: hl-spot

2. Add it to your AI app

Claude Code

claude mcp add reservoir -- uvx --from git+https://github.com/joshavenue/reservoir-mcp reservoir-mcp

Claude Desktop

Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "reservoir": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/joshavenue/reservoir-mcp", "reservoir-mcp"]
    }
  }
}

Restart Claude Desktop. If it says uvx is not found, use the full path from which uvx (for example /Users/you/.local/bin/uvx).

Cursor

~/.cursor/mcp.json: use the same mcpServers block as Claude Desktop.

Codex

~/.codex/config.toml:

[mcp_servers.reservoir]
command = "uvx"
args = ["--from", "git+https://github.com/joshavenue/reservoir-mcp", "reservoir-mcp"]

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "reservoir": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/joshavenue/reservoir-mcp", "reservoir-mcp"]
    }
  }
}

Using a profile other than default? Add "env": { "AWS_PROFILE": "your-profile" }. You can also pass AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (and AWS_SESSION_TOKEN) in env instead of signing in with the CLI.

Then ask: "Run reservoir_setup_check."

Tools

Tool

What it answers

reservoir_setup_check

Does my AWS access work? What is the newest day? How much have I downloaded this month?

reservoir_coverage

What datasets, venues and dates exist? Is something (say, funding) in Reservoir, or which API endpoint has it?

reservoir_list_files

Which files cover a date range, how big they are, and a ready read_parquet(...) snippet (like aws s3 ls)

reservoir_query

Any read-only DuckDB SQL over the bucket, written as in the guide. Estimates the download before running

reservoir_fills

Volume, taker buy/sell, net flow, long/short liquidations, VWAP for a market, a venue or a wallet; breakdowns by minute, hour, day, market or wallet; largest fills

reservoir_candles

OHLCV at 1s to 1d, built from Reservoir's 1-second candles

reservoir_orderbook

Spread, depth within N bps, slippage for an order size, and the full top-20 book at any minute

reservoir_positions

Every open position in a perp market from the daily snapshot: long vs short, leverage, largest positions, liquidation clusters

reservoir_wallet

A wallet's perp positions, spot balances and account values on a given day

reservoir_download

Save whole files locally (like aws s3 cp), then query them for free

The server also has a reservoir://guide resource and a reservoir_guide prompt that tell the agent which tool answers which question.

Market names

Same as in Reservoir itself:

  • Hyperliquid perps: BTC, ETH, kPEPE

  • HIP-3 perps: xyz:MSFT, xyz:ANT, para:BTCD, io:ANTH (case is fixed for you)

  • Spot: @107, PURR/USDC

  • HIP-4 outcomes: #114940

Venues: hyperliquid, xyz (Trade[XYZ]), flx (Felix), vntl (Ventuals), hyna (HyENA), km and mkts (Markets.xyz, which moved from km to mkts in mid-2026), cash (Dreamcash), para (Paragon), io (Entropy).

Times accept 2026-10-26, 2026-10-26T14:00:00Z, 7d, 24h or Unix milliseconds, all UTC. A date-only end includes that whole day.

What it costs

Every result includes aws_usage: megabytes downloaded in that call and your month-to-date total through this server.

  • Reservoir files are sorted by time, and the tools read only the columns and time slices they need. The first 24 hours of xyz:ANT (two days of xyz fills, about 620 MB of files) downloaded 74 MB.

  • Files are not split by market or wallet, so a single-wallet question still reads whole days. Those results suggest the matching Hydromancer API endpoint.

  • Each call stops if its estimate is above max_download_mb (1,024 MB unless you or your agent pass a different value; the highest allowed is set by RESERVOIR_HARD_MAX_DOWNLOAD_MB).

  • Small files (order books, liquidation files, venue snapshots, most candle files) are kept in ~/reservoir-data after the first read, so asking again costs nothing.

  • Running the server on an AWS machine in ap-northeast-1 (Tokyo) makes transfer free.

When Reservoir isn't the right source

Reservoir is a daily archive. It is added to once a day (yesterday's data lands around 10:00 to 12:00 UTC) and never includes today. When a request goes past what it holds, results include a hydromancer_api section naming the endpoint that answers it, with a link to its docs and an example request:

You asked for

Hydromancer API

Today, or anything live

candleSnapshot, fillsByTime, liquidationHistoryByTime, l2Book, WebSocket streams

Positions at any time of day

perpSnapshots, batchClearinghouseStates

Individual orders and who placed them

l4Book, l4BookUpdates

Funding, open interest over time, oracle and mark prices

fundingHistory, openInterestHistory, perpPriceHistoryByTime

One wallet over many days, PnL, deposits and withdrawals

userFillsByTime, userPnlSummary, userNonFundingLedgerUpdates

Slippage and depth over months, or orders bigger than 20 levels can fill

slippageHistory, marketLiquidityHistory

Get an API key. Early-stage teams and public goods may qualify for free access. Questions or data requests: data@hydromancer.xyz.

Settings

Variable

Default

What it does

AWS_PROFILE

default

AWS CLI profile to read credentials from

RESERVOIR_DATA_DIR

~/reservoir-data

Local copies of files, in the bucket's folder layout

RESERVOIR_DEFAULT_MAX_DOWNLOAD_MB

1024

Per-call download limit when a tool call doesn't set one

RESERVOIR_HARD_MAX_DOWNLOAD_MB

20480

Highest limit a tool call may ask for

RESERVOIR_CACHE_MAX_FILE_MB

32

Keep files up to this size locally after first use

RESERVOIR_QUERY_TIMEOUT_S

300

Stop a query after this many seconds

RESERVOIR_AWS_CLI

found on PATH

Full path to aws if your app can't find it

Safety

  • Read-only toward Hyperliquid: no trading, no signing, no private keys.

  • The DuckDB connection can read only s3://hydromancer-reservoir/ and the local data folder. Writing files, attaching databases, installing extensions and changing settings are blocked, and reservoir_query accepts a single SELECT.

  • Your AWS credentials stay on your machine. They are read from the AWS CLI or your environment and used only to sign requests to the Reservoir bucket.

Development

git clone https://github.com/joshavenue/reservoir-mcp && cd reservoir-mcp
uv sync
uv run pytest -q                     # offline unit tests
uv run python scripts/smoke.py       # end-to-end over stdio (needs AWS, a few MB)
uv run python scripts/live_check.py  # every tool against live data (needs AWS, a few hundred MB)

Data definitions follow Hydromancer's docs: fills have one row per account side, volume counts the taker side only, open interest from snapshots is two-sided. See the schema reference.

License

MIT

Available Tools

10 tools
reservoir_candlesCandles from 1-second dataA
Read-onlyIdempotent

OHLCV candles at any interval, rolled up from Reservoir's 1-second candles (up to 1,500 candles per call).

Inputs: market (required), end, start, interval, +1 more. Returns: object

reservoir_coverageWhat Reservoir coversA
Read-onlyIdempotent

Datasets, bucket paths, market naming, venues with their first and newest day, update schedule and AWS cost. With topic, says whether Reservoir holds it and, if not, which Hydromancer API endpoint does.

Inputs: topic, venue. Returns: object

reservoir_downloadDownload Reservoir filesA
Idempotent

Like aws s3 cp: save whole Parquet files to the local Reservoir folder (RESERVOIR_DATA_DIR, default ~/reservoir-data), keeping the bucket's folder layout. Files already there are skipped. Use for repeated analysis.

Inputs: dataset (required), end, start, venue, +2 more. Returns: object

reservoir_fillsFills, volume and liquidationsA
Read-onlyIdempotent

Trades for a market, a venue or a wallet over any past window: taker volume, buy/sell split, net flow, long/short liquidations, VWAP, high/low, wallets, plus optional breakdowns and raw fills.

Inputs: end, kind, rows, start, +7 more. Returns: object

reservoir_list_filesList Reservoir filesA
Read-onlyIdempotent

Like aws s3 ls: the exact Parquet files for a dataset and date range, their sizes, the full-download cost and a ready read_parquet(...) snippet for reservoir_query. Lists only; downloads nothing.

Inputs: dataset (required), end, start, venue, +1 more. Returns: object

reservoir_orderbookOrder book: spread, depth, slippageA
Read-onlyIdempotent

Minute-by-minute top-20 L2 books: mid, spread, USD depth within N bps, optional slippage for an order size, medians over the window, and the full book at a given minute (max 31 days).

Inputs: market (required), at, end, every, +3 more. Returns: object

reservoir_positionsWho holds a perp marketA
Read-onlyIdempotent

Every open position in a perp market from the daily snapshot: long vs short accounts and notional, average entry, leverage, largest positions with liquidation prices, and where liquidations cluster.

Inputs: market (required), top, date. Returns: object

reservoir_queryRun SQL on ReservoirA
Read-onlyIdempotent

Run DuckDB SQL directly on the Reservoir bucket, exactly like the exploring-reservoir blog. Before running, estimates the download from the columns the query reads and refuses above max_download_mb. Only the Reservoir bucket and local Reservoir copies can be read. Prefer the dedicated tools for fills, candles, books and positions.

Inputs: sql (required), dry_run, max_rows, max_download_mb. Returns: object

reservoir_setup_checkCheck Reservoir accessA
Read-onlyIdempotent

Check AWS sign-in, requester-pays access to the Reservoir bucket, DuckDB, the local data folder and this month's download total. Run this first, or whenever a tool reports a credentials error.

Inputs: no named parameters. Returns: object

reservoir_walletOne wallet's daily snapshotA
Read-onlyIdempotent

A wallet's perp positions, spot balances and account values on a given day, from the global snapshots. These files are not split by wallet, so each part scans the whole day's file.

Inputs: address (required), date, include, max_download_mb. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools target clearly distinct resources or actions: setup, coverage, file listing, specialized market-data queries, and file downloads. The broad reservoir_query overlaps with the specialized fills/candles/orderbook/positions tools, but its description explicitly says to prefer the dedicated tools, reducing misselection risk.

    Naming Consistency4/5

    All tools use the consistent reservoir_ prefix and snake_case, which makes them easy to scan and group. The set mixes action-like names (list_files, setup_check, download) with resource-like names (fills, candles, orderbook), so it is not a perfect verb_noun convention, but it remains predictable.

    Tool Count5/5

    Ten tools is well-scoped for a specialized market-data access server. Each tool has a clear role: setup, discovery, listing, querying, specialized data views, and downloading.

    Completeness5/5

    The surface covers the full read-only lifecycle for this domain: credential/setup checking, dataset discovery, file listing, SQL access, common analytical queries, and local downloads. The generic reservoir_query provides an escape hatch for any dataset not covered by the specialized tools, so there are no obvious dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides comprehensive crypto intelligence for the Hyperliquid exchange, allowing users to query trader profiles, behavioral cohorts, and live market data. It enables AI agents to analyze over 1.8 billion trades, track whale positions, and access real-time liquidation heatmaps.
      106
      59 npm
      10
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to query Hyperliquid spot market data, including token listings, live prices, 24h volumes, and wallet balances, via pay-per-call x402 micropayments.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides AI agents read-only, keyless access to Hyperliquid market data, funding rates, account risk, and HyperEVM token transfers through MCP tools, with caching and rate limiting to protect upstream APIs.
      12
      85 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to read live Hyperliquid market data — perp and spot metadata, mid prices, order books, OHLCV candles, funding rates and history, and current open interest — keylessly from the exchange's public info API, with no wallet or trading access.
      105 npm
      MIT