mcpxyz 0.4.0

MCP server for trade.xyz: analysis and trading of the xyz HIP-3 markets (xyz:AAPL, xyz:GOLD, ...) on Hyperliquid, with in-code guardrails.

mcpxyz - MCP server for trade.xyz (HIP-3 on Hyperliquid)

An MCP server that lets an AI assistant (Claude Desktop, Claude Code, …) analyse and trade the xyz markets - tokenized equities, commodities and indices like xyz:AAPL, xyz:GOLD, xyz:NVDA, xyz:XYZ100 - exposed by trade.xyz.

trade.xyz has no proprietary API: it is a UI over the xyz HIP-3 perp dex deployed on Hyperliquid. Everything here goes through the standard Hyperliquid API, with markets namespaced xyz:.

⚠️ Not financial advice. Trading involves risk of loss. Use at your own risk.

Safety model

This server signs financial transactions, so guardrails are enforced in code (not via the prompt):

• Read-only by default - no order is signed unless READ_ONLY=false and a key is set.
• Delegated API wallet only - use a Hyperliquid API wallet (no withdrawal rights). The withdraw tool has been removed entirely.
• Asset whitelist - writes are limited to ALLOWED_ASSETS (empty ⇒ all writes blocked).
• Per-order caps - MAX_ORDER_SIZE, MAX_ORDER_NOTIONAL_USD, MAX_LEVERAGE.
• Two-step orders - place_order returns a preview + token; nothing is signed until you call confirm_order.
• Kill switch - cancel_all_orders is always available and never whitelisted.

See SECURITY.md for the full policy and key-handling guidance.

Tools

Market data (read-only): get_markets_overview (all markets in one call - price, 24h change, funding, OI, volume; sortable for top movers), get_market_data, get_candle_data, get_l2_orderbook, get_funding_rates, calculate_min_order_size.

Account: get_positions (xyz isolated margin account), get_spot_user_state, get_user_fees, update_leverage, transfer (move collateral between core / spot / xyz).

Orders: place_order (preview) → confirm_order, cancel_order, cancel_all_orders, bulk_cancel_orders, modify_order, get_open_orders, get_order_status, get_user_fills, get_user_fills_by_time.

Assets are accepted namespaced (xyz:AAPL) or bare (AAPL, apple) - they are normalized automatically.

Requirements

Python 3.11+ and one launcher: uv (recommended), pip, or pipx.

Works with any MCP client

mcp-xyz speaks standard MCP (stdio / HTTP / SSE), so it works with any MCP-compatible client - regardless of the underlying LLM: Claude Desktop, Claude Code, Cursor, Cline, Continue, Windsurf, Zed, or your own agent via the Python / TypeScript MCP SDKs. The examples below use Claude Desktop's config format; other clients use the same command + args (+ env) in their own config file.

Get a delegated API wallet (trading only)

1. In the Hyperliquid / trade.xyz UI, create an API wallet (a.k.a. agent wallet). It can trade but cannot withdraw funds.
2. Copy its private key → this is your HYPERLIQUID_PRIVATE_KEY. Never use your main account key.

Install - three ways

1. Clone the repo (best for builders)

Get the code, keep your config in a gitignored .env, and let your IDE agent wire it in.

git clone https://github.com/akugone/mcp-xyz
cd mcp-xyz
cp .env.example .env    # analysis: leave as-is · trading: add your API wallet key

Then either ask your IDE agent (Claude Code, Cursor, …) to "add this repo as an MCP server" - it reads this README and wires it up - or add it manually:

{ "mcpServers": { "xyz": {
  "command": "uv",
  "args": ["--directory", "/absolute/path/to/mcp-xyz", "run", "mcpxyz"]
} } }

The .env in the folder is loaded automatically, so all config lives there (no env block needed). For Claude Code, one command does it:

claude mcp add xyz -- uv --directory /absolute/path/to/mcp-xyz run mcpxyz

2. From PyPI (recommended for users)

No clone. Generate a ready-to-paste config with init:

uvx mcpxyz init            # analysis (read-only)
uvx mcpxyz init --trading  # with a trading env block to fill in

Paste the snippet into your client's config, fill your key if trading, restart the client. No uv? pip install mcpxyz (then use mcpxyz as the command) or pipx run mcpxyz - same result.

3. Claude Desktop (copy-paste)

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows). Merge the xyz entry and fully restart Claude Desktop.

Analysis only - zero config, no key:

{
  "mcpServers": {
    "xyz": { "command": "uvx", "args": ["mcpxyz"] }
  }
}

Reads (prices, funding, candles, orderbook) work immediately. No key ⇒ fully read-only, no order can be placed.

Trading - add your own delegated API wallet key:

{
  "mcpServers": {
    "xyz": {
      "command": "uvx",
      "args": ["mcpxyz"],
      "env": {
        "HYPERLIQUID_PRIVATE_KEY": "0x<your_delegated_api_wallet_key>",
        "HYPERLIQUID_USER_ADDRESS": "0x<your_main_account_address>",
        "READ_ONLY": "false",
        "ALLOWED_ASSETS": "xyz:*",
        "MAX_ORDER_NOTIONAL_USD": "100"
      }
    }
  }
}

ALLOWED_ASSETS: "xyz:*" allows trading every xyz market. To restrict trading to specific markets, list them instead, e.g. "xyz:AAPL,xyz:GOLD".

Your key stays on your machine - it is only read from this env block (or, for local development, a gitignored .env) and never sent anywhere.

Environment variables

Variable	Default	Description
HYPERLIQUID_PRIVATE_KEY	-	Delegated API wallet key. Empty ⇒ read-only.
HYPERLIQUID_USER_ADDRESS	wallet addr	Address to query positions/fills for.
HYPERLIQUID_TESTNET	false	Use testnet instead of mainnet.
READ_ONLY	true	Must be false (and a key set) to sign anything.
XYZ_DEX	xyz	HIP-3 perp dex namespace.
ALLOWED_ASSETS	-	Comma-separated whitelist for writes (e.g. xyz:AAPL,xyz:GOLD). xyz:* allows all xyz markets. Empty ⇒ writes blocked. Reads are never restricted.
MAX_ORDER_SIZE	-	Max size per order.
MAX_ORDER_NOTIONAL_USD	-	Max notional (USD) per order.
MAX_LEVERAGE	-	Max leverage for update_leverage.
HYPERLIQUID_MCP_SHOW_LOGS	false	Keep false in production.

Usage flow

1. Explore read-only: get_market_data xyz:AAPL → candles → L2 → funding.
2. Check get_positions.
3. place_order (limit, away from the price) → review the preview → confirm_order.
4. cancel_order / cancel_all_orders.

Validation & tests

• uv run pytest - offline unit tests (guardrails, models, tool registration, order flow).
• Write-path validation on testnet: see docs/VALIDATION.md and scripts/validate_testnet.py.

Transports

mcpxyz                       # stdio (default)
mcpxyz --transport http --port 3000
mcpxyz --transport sse  --port 3000

Credits & license

Licensed under MIT. Includes MIT-licensed code from midodimori/hyperliquid-mcp, adapted for the trade.xyz HIP-3 markets with in-code guardrails.