# Reservoir MCP

Let your AI agent work with [Reservoir](https://docs.hydromancer.xyz/reservoir), Hydromancer's free archive of Hyperliquid history, the same way the [Exploring Reservoir](https://hydromancer.xyz/blog/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](https://docs.hydromancer.xyz) 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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
2. Sign in: `aws login` (or use a named profile with a read-only IAM user; see the [guide](https://hydromancer.xyz/blog/exploring-reservoir) for the policy).
3. Check it works:

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

You also need [uv](https://docs.astral.sh/uv/getting-started/installation/), which runs the server.

## 2. Add it to your AI app

### Claude Code

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

### Claude Desktop

Settings → Developer → Edit Config, then add:

```json
{
  "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`:

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

### VS Code (GitHub Copilot)

`.vscode/mcp.json`:

```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](https://docs.hydromancer.xyz/readme/get-api-keys). Early-stage teams and public goods [may qualify for free access](https://docs.hydromancer.xyz/readme/hydromancer-for-early-stage-teams). 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

```bash
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](https://docs.hydromancer.xyz/reservoir/schema-reference).

## License

MIT