Worm MCP

Browse, trade, and manage prediction markets from any AI agent.

🌐 Worm  ·  📖 Docs  ·  📦 worm-sdk  ·  🐛 Issues  ·  ⚖️ MIT

Installation

worm-mcp runs over stdio; your MCP client launches it on demand. Set WALLET_PRIVATE_KEY to enable authenticated and trading tools, or omit it to use only the public, read-only tools.

Pick the flow that fits you:

• For users: you just want to use the tool in your MCP client. Your client launches it with uvx; no manual install.
• For developers: you want to modify the code. Clone the repo and run it from a local editable install.

For users

Your client launches worm-mcp on demand; uvx fetches and runs it for you.

Claude Code: register it once from the CLI; --scope user makes it available in every project:

claude mcp add --scope user worm \
  -e WALLET_PRIVATE_KEY=<base58-solana-private-key> \
  -- uvx worm-mcp

Confirm with claude mcp list (shows worm … ✓ Connected).

Cursor: add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project), then enable it under Settings → MCP:

{
  "mcpServers": {
    "worm": {
      "command": "uvx",
      "args": ["worm-mcp"],
      "env": { "WALLET_PRIVATE_KEY": "<base58-solana-private-key>" }
    }
  }
}

Claude Desktop: Settings → Developer → Edit Config opens claude_desktop_config.json; add the same mcpServers block and restart the app.

Other clients (Windsurf, Cline, Zed, VS Code, …): same launch: command uvx, args ["worm-mcp"], plus the WALLET_PRIVATE_KEY env. Only the config file location differs.

No uv? pipx run worm-mcp or pip install worm-mcp work too.

For developers

Run worm-mcp from a local clone, for hacking on the code or running an unpublished build. Clone and set up an editable environment:

git clone https://github.com/wormwtf/worm-mcp.git
cd worm-mcp
uv venv
uv pip install -e ".[dev]"
uv run ruff check src
WALLET_PRIVATE_KEY=... worm-mcp     # run the stdio server directly

Point your client at the editable checkout so code changes take effect on the next client restart. Either add --with-editable to the uvx launch:

claude mcp add --scope user worm \
  -e WALLET_PRIVATE_KEY=<base58-solana-private-key> \
  -- uvx --from /path/to/worm-mcp --with-editable /path/to/worm-mcp worm-mcp

…or point the client's command straight at the venv binary the editable install creates (args can be omitted):

{
  "mcpServers": {
    "worm": {
      "command": "/path/to/worm-mcp/.venv/bin/worm-mcp",
      "env": { "WALLET_PRIVATE_KEY": "<base58-solana-private-key>" }
    }
  }
}

Verify

Ask your client "List trending markets on Worm" (public) or "What's my Worm account summary?" (confirms auth): a sensible answer means it's wired up.

Requirements

• An MCP client (Claude Code, Cursor, Claude Desktop, …)
• uv (or pipx / pip)
• A funded Solana wallet (only for trading and other authenticated tools)

Environment variables

Tools

Public (no credentials)

Authenticated read (HMAC)

Authenticated write (HMAC)

Authenticated write: local signing (needs WALLET_PRIVATE_KEY)

Notes for agents

• Spot vs margin: place_order is for non-margin (orderbook) markets; use open_margin_position when margin_enabled=true. Margin markets are backed by an external venue and quote from that backend's book; size leveraged positions with estimate_margin_position rather than reading depth from get_orderbook.
• Margin lifecycle: open_margin_position returns a position-request pubkey; the actual position appears via list_margin_positions (match position_request_pubkey) once funding completes. TP/SL is unsupported on Hyperliquid-backed markets.
• Leverage: always call estimate_margin_position and confirm with the user before opening; leverage carries liquidation risk.
• Docs on demand: call read_worm_docs with no arguments for the index, then pass a path for exact API schemas and examples.

Features

• 38 tools across markets, events, search, sports, account, orders, trades, margin, redeems, key management, and docs
• Local Solana keypair signing, so your private key never leaves the MCP process
• Auto-bootstrapped HMAC credentials: set one env var and the rest is automatic
• Public market data works with no credentials at all
• Built on the official worm-sdk, with full type hints

Architecture

┌──────────────┐  stdio   ┌────────────┐  HTTPS + HMAC  ┌──────────────┐
│  MCP client  │ ◀──────▶ │  worm-mcp  │ ◀────────────▶ │  Worm API    │
│ (Claude etc.)│          │  (Python)  │                │ api.worm.wtf │
└──────────────┘          └─────┬──────┘                └──────────────┘
                                │ ed25519 signing (orders, margin, redeems)
                                ▼
                          worm-sdk + solders (local keypair)

See rate limits in the docs. Markets are viewable at https://worm.wtf/market/{condition_id}.

Security

• Your private key is used only to sign transactions locally; it is never sent to the Worm API or any third party.
• Bootstrapped HMAC credentials are cached at ~/.worm/config.json with 0600 permissions, keyed by API base URL and wallet, so multiple wallets or environments (e.g. WORM_API_BASE overrides) each keep their own credentials instead of clobbering one another. Writes are atomic and locked, so concurrent clients can't corrupt or lose cached credentials.
• Use a dedicated wallet funded with only what you intend to trade, and keep the key out of version control and shared configs.

Troubleshooting

• uvx: command not found: install uv, or use pipx run worm-mcp / pip install worm-mcp.
• Tools don't appear: fully restart the client; it spawns the server once at startup. In Claude Code, check claude mcp list.
• Authentication errors: confirm WALLET_PRIVATE_KEY is a valid base58 Solana key; delete ~/.worm/config.json to force a fresh credential bootstrap.