Hydromancer MCP server
Commit Oct 30, 2026Allows an AI client to query Hyperliquid market data, wallet balances, top traders, and liquidations using plain English.
Also known as joshavenue/hydromancer-mcp-python
- Stars
- 0
- Tools
- 12
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 30, 2026
- License
- MIT
What is Hydromancer MCP?
Hydromancer allows an AI client to query Hyperliquid market data, wallet balances, top traders, and liquidations using plain English. It exposes 12 tools, such as hydromancer_wallet_overview, hydromancer_wallet_trades, hydromancer_wallet_closed_trades.
Summary generated from the project's README
About Hydromancer MCP server
Querying Hyperliquid market data and wallet details through natural language is what this Python-based MCP server enables. Designed for traders and developers using AI clients like Claude Desktop, Cursor, or Claude Code, it provides a read-only interface to the Hydromancer API. Users can investigate market snapshots, funding history, recent liquidations, and order book depth without writing complex code.
To use the server, you must provide a Hydromancer API key via the HYDROMANCER_API_KEY environment variable. It connects to the main API or a testnet if you configure the HYDROMANCER_BASE_URL. The server includes 12 specialized tools, such as hydromancer_wallet_overview for checking balances and human scores, and hydromancer_top_traders for identifying profitable participants. Because it is strictly read-only, it cannot execute trades or handle private keys, ensuring your funds remain secure while you gather intelligence.
What you can do with it
- 1Analyze trader performanceAsk the AI to evaluate a specific wallet address to see if the user is a skilled trader.
- 2Identify market liquidationsRequest a summary of recent liquidations to understand recent market volatility.
- 3Monitor top market participantsFind the most profitable traders over a specific period while filtering out automated bots.
- 4Check market liquidityDetermine how much slippage to expect for a specific trade size by checking order book depth.
Written from the project's README. Every use case is checked against a quote from it.
Hydromancer MCP tools 12
Detected from the READMEhydromancer_wallet_overviewhydromancer_wallet_tradeshydromancer_wallet_closed_tradeshydromancer_top_tradershydromancer_market_snapshothydromancer_price_historyhydromancer_funding_historyhydromancer_recent_liquidationshydromancer_market_depthhydromancer_list_marketshydromancer_my_usagehydromancer_raw_request
| hydromancer_wallet_overview | — | |
| hydromancer_wallet_trades | — | |
| hydromancer_wallet_closed_trades | — | |
| hydromancer_top_traders | — | |
| hydromancer_market_snapshot | — | |
| hydromancer_price_history | — | |
| hydromancer_funding_history | — | |
| hydromancer_recent_liquidations | — | |
| hydromancer_market_depth | — | |
| hydromancer_list_markets | — | |
| hydromancer_my_usage | — | |
| hydromancer_raw_request | — |
Configuration
HYDROMANCER_API_KEYHYDROMANCER_LIVE
| Name | Description | |
|---|---|---|
| HYDROMANCER_API_KEY | — | |
| HYDROMANCER_LIVE | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejoshavenue/hydromancer-mcp-python is public and reachablegithub.com/joshavenue/hydromancer-mcp-python ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-30github.com/joshavenue/hydromancer-mcp-python ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model12 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubhydromancer-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
/infoendpoints - Friendly inputs: coin names in any case (
btc,$ETH,ETH-PERP,xyz:tsla), times like24h,7dor2026-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
httpxandpydantic; Python 3.10+
Hosts contacted
The server makes HTTPS requests to one of these hosts:
| Host | When |
|---|---|
api.hydromancer.xyz |
Every tool call (default) |
api-testnet.hydromancer.xyz |
Instead of the above, only if you set HYDROMANCER_BASE_URL to the testnet URL |
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
| Tool | What it answers |
|---|---|
hydromancer_wallet_overview |
Balance (handles unified-account and portfolio-margin wallets), open positions with entry, liquidation price, leverage and PnL, spot balances, trading record, human score (low suggests a bot) |
hydromancer_wallet_trades |
Fills in a time window, with volume, PnL, fees and per-coin totals |
hydromancer_wallet_closed_trades |
Round-trip trades: win rate, net PnL, hold time, best coin |
hydromancer_top_traders |
Leaderboard by profit, win rate or volume, with bot and activity filters |
hydromancer_market_snapshot |
Price, 24h volume, open interest; max leverage in the top-markets list |
hydromancer_price_history |
Candles from 1 second to 1 month |
hydromancer_funding_history |
Funding rates, average and annualized |
hydromancer_recent_liquidations |
Liquidations by market, with long/short totals |
hydromancer_market_depth |
Order book depth and slippage for a trade size |
hydromancer_list_markets |
Every market and HIP-3 exchange, searchable by name or category |
hydromancer_my_usage |
Your own API usage |
hydromancer_raw_request |
Any other Hydromancer /info request, e.g. open orders, transfers, vaults (endpoint list) |
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
| Variable | Default | Purpose |
|---|---|---|
HYDROMANCER_API_KEY |
(required) | Your API key |
HYDROMANCER_BASE_URL |
https://api.hydromancer.xyz/info |
Set to https://api-testnet.hydromancer.xyz/info for testnet; any other host is refused |
HYDROMANCER_TIMEOUT_MS |
30000 |
Request timeout |
HYDROMANCER_MAX_RESULT_CHARS |
40000 |
Cap on one tool result (minimum 1000), so the AI is not flooded |
Security
- Read-only. Every request goes to the
/infoendpoint, 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
Authorizationheader 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_requestresults 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-Afterheader 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
balanceUsduses 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
Hydromancer MCP questions
What tools does Hydromancer MCP provide?
It exposes 12 tools, including hydromancer_wallet_overview, hydromancer_wallet_trades, hydromancer_wallet_closed_trades, hydromancer_top_traders, hydromancer_market_snapshot.
What information can I get about a specific wallet?
You can retrieve balance information, open positions, entry prices, liquidation prices, leverage, PnL, spot balances, and trading records.
How do I use the testnet instead of the mainnet?
You can use the testnet by setting the HYDROMANCER_BASE_URL environment variable to the testnet URL.
Does the server require an API key?
Yes, you need a Hydromancer API key to use the server.