Reservoir MCP
Reads Hyperliquid/HIP-3 history from Amazon S3: queries Parquet files in the Hydromancer Reservoir bucket (s3://hydromancer-reservoir) using the user's AWS credentials (AWS CLI profile or env vars), with requester-pays downloads. Estimates download size before each call, enforces a per-call MB limit, caches small files locally, and reports per-call and month-to-date data transfer so AWS costs stay visible.
Runs read-only DuckDB SQL over Reservoir's Parquet data straight from S3, matching the layout and market naming of Hydromancer's Exploring Reservoir guide. Queries are restricted to a single SELECT against the Reservoir bucket and local cache, with column/time-slice pruning to minimize downloads, query timeouts, and downloadable local copies of files for free re-querying.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Reservoir MCP Show hourly BTC candles for October 1."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_querycan runWatches 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.
Install the AWS CLI v2.
Sign in:
aws login(or use a named profile with a read-only IAM user; see the guide for the policy).Check it works:
aws s3 ls s3://hydromancer-reservoir/ --request-payer requester --region ap-northeast-1You 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-mcpClaude 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 |
| Does my AWS access work? What is the newest day? How much have I downloaded this month? |
| What datasets, venues and dates exist? Is something (say, funding) in Reservoir, or which API endpoint has it? |
| Which files cover a date range, how big they are, and a ready |
| Any read-only DuckDB SQL over the bucket, written as in the guide. Estimates the download before running |
| 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 |
| OHLCV at 1s to 1d, built from Reservoir's 1-second candles |
| Spread, depth within N bps, slippage for an order size, and the full top-20 book at any minute |
| Every open position in a perp market from the daily snapshot: long vs short, leverage, largest positions, liquidation clusters |
| A wallet's perp positions, spot balances and account values on a given day |
| Save whole files locally (like |
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,kPEPEHIP-3 perps:
xyz:MSFT,xyz:ANT,para:BTCD,io:ANTH(case is fixed for you)Spot:
@107,PURR/USDCHIP-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 byRESERVOIR_HARD_MAX_DOWNLOAD_MB).Small files (order books, liquidation files, venue snapshots, most candle files) are kept in
~/reservoir-dataafter 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 |
|
Positions at any time of day |
|
Individual orders and who placed them |
|
Funding, open interest over time, oracle and mark prices |
|
One wallet over many days, PnL, deposits and withdrawals |
|
Slippage and depth over months, or orders bigger than 20 levels can fill |
|
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 CLI profile to read credentials from |
|
| Local copies of files, in the bucket's folder layout |
|
| Per-call download limit when a tool call doesn't set one |
|
| Highest limit a tool call may ask for |
|
| Keep files up to this size locally after first use |
|
| Stop a query after this many seconds |
| found on PATH | Full path to |
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, andreservoir_queryaccepts a singleSELECT.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 toolsreservoir_candlesCandles from 1-second dataARead-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 coversARead-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 filesAIdempotent
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 liquidationsARead-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 filesARead-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, slippageARead-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 marketARead-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 ReservoirARead-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 accessARead-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 snapshotARead-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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Hyperliquid market data, wallet analytics and liquidation alerts for AI agents.
Version 2.8.0. HyperNatt Terminal: liquidation radar, Hyperliquid execution context and Li.Fi cross-chain swap for AI agents. BTC ETH SOL BNB XRP HYPE ZEC. Before an order: estimate depth, VWAP, spread and fees for its size. Between checks: compare liquidity and costs with the previous baseline. After execution: reconcile supplied fills. Read-only data, no custody or order submission. 6 tools, v2.8.0; call get_agent_manifest first. Radar and each execution-context call cost 0.001 USDC via x402 Base/Solana or eligible credits; manifest and MCP swap quote are free (on-chain swap fees apply). Daily MCP trial: one free call per paid tool and per token per client each UTC day. Four tools x seven tokens = up to 28 independent trials; then 0.001 USDC per call. Read trial_policy_v2 and free_tier_status_v1 on the same MCP connection for current availability. A zero daily_cap is the separate credit pool, not the intro allowance. Full platform: https://hypernatt.com. Docs: github.com/DIALLOUBE-RESEARCH/hypernatt-terminal.
Polymarket + Hyperliquid + macro for AI agents. 38 tools, signal backtest, SSE streaming. Free tier.
Polymarket orderbook history, live books, trades and settlements, plus Hyperliquid perp books.
Related MCP Servers
AlicenseAqualityBmaintenanceProvides 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.10659 npm10MIT- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseAqualityBmaintenanceProvides 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.1285 PyPI1MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT