hydromancer-mcp

Read-only MCP server for the Hydromancer Hyperliquid API, in Python. Ask your AI app about wallets, top traders, markets, funding and liquidations in plain English.

Disclosure: this package is maintained by the Hydromancer team. You need a Hydromancer API key to use it.

uvx hydromancer-mcp

• "What is this wallet holding, and is it a good trader?"
• "Who were the best traders this week, without bots?"
• "Who got liquidated in the last 6 hours?"
• "How much BTC can I sell before the price moves 0.5%?"

• 12 read-only tools: wallets, trades, top traders, markets, funding, depth, liquidations, your API usage, plus a raw request tool for other /info endpoints
• Friendly inputs: coin names in any case (btc, $ETH, ETH-PERP, xyz:tsla), times like 24h, 7d or 2026-10-01
• Read-only: it cannot place, cancel or sign orders, and it never handles funds or private keys
• Few dependencies: besides the MCP SDK it uses only httpx and pydantic; Python 3.10+

Hosts contacted

The server makes HTTPS requests to one of these hosts:

Any other HYDROMANCER_BASE_URL is refused at startup, so your key cannot be sent elsewhere. Redirects are not followed. No telemetry. (Installing with uvx or pip downloads the package from PyPI; the server itself never contacts PyPI.)

1. Get a Hydromancer API key

See Get API keys.

2. Add it to your AI app

You need uv (for uvx). Replace YOUR_KEY with your key.

Claude Desktop

Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "hydromancer": {
      "command": "uvx",
      "args": ["hydromancer-mcp"],
      "env": { "HYDROMANCER_API_KEY": "YOUR_KEY" }
    }
  }
}

Restart Claude Desktop. If it cannot find uvx, use the full path from which uvx as the command.

Claude Code

claude mcp add hydromancer -e HYDROMANCER_API_KEY=YOUR_KEY -- uvx hydromancer-mcp

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "hydromancer": {
      "command": "uvx",
      "args": ["hydromancer-mcp"],
      "env": { "HYDROMANCER_API_KEY": "YOUR_KEY" }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.hydromancer]
command = "uvx"
args = ["hydromancer-mcp"]
env = { HYDROMANCER_API_KEY = "YOUR_KEY" }

Other MCP apps, or pip

Any app that runs stdio MCP servers works with uvx hydromancer-mcp. Without uv:

pip install hydromancer-mcp
hydromancer-mcp --help

3. Ask

• Give me an overview of wallet 0x… and tell me if it's a good trader.
• Show the top 10 traders by profit over the last 7 days, no bots, then what the top 3 hold right now.
• Who got liquidated on Hyperliquid in the last 6 hours? Longs or shorts?
• BTC, ETH and HYPE: price, 24h volume and open interest.
• What's the BTC funding rate averaged over the last week, annualized?
• How deep is the xyz:TSLA order book within 1% of the price?

Tools

The server also provides a hydromancer_guide prompt and a hydromancer://guide resource that tell the AI which tool to use for which question.

Settings

Security

• Read-only. Every request goes to the /info endpoint, which only returns data.
• What is sent. Only the requests needed for each tool call (the wallet addresses, coin names and time ranges you ask about, plus a market-list lookup to resolve coin names), your key, and a User-Agent naming this package and its version, to the hosts above.
• Your key stays local. It is read from the environment, sent only in the Authorization header to the hosts above, never logged or printed, and replaced with *** if it ever appears in an error message.
• Responses are data, not instructions. API responses (market names, descriptions, any text field) are returned to the AI as data. The server tells the AI to treat them as data and never to follow instructions found inside them, and hydromancer_raw_request results carry the same note. This is guidance to the AI, not a guarantee, so review what your AI app does with the results.
• Rate limits. On HTTP 429 the server retries at most twice, waiting as long as the API asks (the Retry-After header or the response body, otherwise 1 s then 2 s, plus a fraction of a second), but only if that wait is 10 seconds or less. Otherwise it tells the AI how long to wait.
• Size limits. Responses over 64 MB are refused, and each tool result is capped (see HYDROMANCER_MAX_RESULT_CHARS) with a note when it is cut.

Good to know

• The data is for information only and is not financial advice.
• Each tool call makes one or more ordinary API requests (some tools combine several, and coin names are checked against the market list), and each request counts toward your key's usage. Check it with hydromancer_my_usage.
• HIP-3 markets use a prefix, for example xyz:TSLA.
• Balances: unified-account and portfolio-margin wallets keep their money in spot, so balanceUsd uses their spot stablecoins. Other spot tokens are listed but not priced.
• Times are UTC. Some endpoints cap a single request (for example 2,000 fills); the tool says so when it happens.
• Binary snapshot endpoints are not supported.

Development

uv sync
uv run pytest                              # offline unit tests (HTTP mocked with respx)
HYDROMANCER_LIVE=1 HYDROMANCER_API_KEY=... uv run pytest -m live   # opt-in live tests
HYDROMANCER_API_KEY=... uv run python scripts/smoke_stdio.py       # real stdio round trip

License

MIT © Hydromancer BV