Crush Protocol MCP Client

MCP server for connecting AI coding agents to Crush — market data, backtests, live strategies, and trading.

Quick Start

npx -y @crush-protocol/mcp-client@latest setup --cursor   # Cursor
npx -y @crush-protocol/mcp-client@latest setup --claude    # Claude Code
npx -y @crush-protocol/mcp-client@latest setup --all       # all supported hosts

OAuth login is explicit. On first tool call, Crush prints or returns an authorization URL for the user to open manually in a browser.

Install

Recommended:

npx -y @crush-protocol/mcp-client@latest setup --all

This writes MCP config for all supported hosts at once. To target a single host:

npx -y @crush-protocol/mcp-client@latest setup --cursor
npx -y @crush-protocol/mcp-client@latest setup --claude
npx -y @crush-protocol/mcp-client@latest setup --codex
npx -y @crush-protocol/mcp-client@latest setup --gemini
npx -y @crush-protocol/mcp-client@latest setup --opencode
npx -y @crush-protocol/mcp-client@latest setup --vscode
npx -y @crush-protocol/mcp-client@latest setup --windsurf
npx -y @crush-protocol/mcp-client@latest setup --claude-desktop
npx -y @crush-protocol/mcp-client@latest setup --warp

Cursor and VS Code also support --scope project for repo-local config.

Client Configuration

Auto setup:

npx -y @crush-protocol/mcp-client@latest setup --cursor

Manual config: Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Auto setup:

npx -y @crush-protocol/mcp-client@latest setup --claude

Manual config:

claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client@latest

Auto setup:

npx -y @crush-protocol/mcp-client@latest setup --codex

Manual config:

CLI: codex mcp add crush-protocol -- npx -y @crush-protocol/mcp-client@latest

File: Add to ~/.codex/config.toml:

[mcp_servers.crush-protocol]
command = "npx"
args = ["-y", "@crush-protocol/mcp-client@latest"]
startup_timeout_sec = 60

Auto setup:

npx -y @crush-protocol/mcp-client@latest setup --gemini

Manual config: Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Auto setup:

npx -y @crush-protocol/mcp-client@latest setup --vscode

Manual config: Add to .vscode/mcp.json (project) or ~/.vscode/mcp.json (global):

{
  "servers": {
    "crush-protocol": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Auto setup:

npx -y @crush-protocol/mcp-client@latest setup --windsurf

Manual config: Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Auto setup:

npx -y @crush-protocol/mcp-client@latest setup --claude-desktop

Manual config: Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Auto setup:

npx -y @crush-protocol/mcp-client@latest setup --opencode

Manual config: Add to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "crush-protocol": {
      "type": "local",
      "command": ["npx", "-y", "@crush-protocol/mcp-client@latest"],
      "enabled": true
    }
  }
}

Auto setup:

npx -y @crush-protocol/mcp-client@latest setup --warp

Manual config: Add via Warp Drive → MCP Servers → + Add:

{
  "crush-protocol": {
    "command": "npx",
    "args": ["-y", "@crush-protocol/mcp-client@latest"],
    "env": {},
    "working_directory": null,
    "start_on_launch": true
  }
}

Add to ~/.kiro/settings/mcp.json (global) or .kiro/settings/mcp.json (workspace):

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add to .roo/mcp.json (project) or open Roo Code settings → Edit Global MCP:

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add to cline_mcp_settings.json (open via Cline panel → MCP Servers → Configure MCP Servers):

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add via Trae → Settings → MCP → Add MCP Server:

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add via Settings → Tools → + Add MCP → Command: npx -y @crush-protocol/mcp-client@latest

"augment.advanced": {
  "mcpServers": [
    {
      "name": "crush-protocol",
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  ]
}

Add to .github/copilot/mcp.json in your repository:

{
  "mcpServers": {
    "crush-protocol": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "crush-protocol": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add to ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

amp mcp add crush-protocol -- npx -y @crush-protocol/mcp-client@latest

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "crush-protocol": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add via Settings → Tools → AI Assistant → Model Context Protocol (MCP) → + Add:

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

CLI: qwen mcp add crush-protocol npx -y @crush-protocol/mcp-client@latest

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add to mcp.json (open via Program → Install → Edit mcp.json):

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add to .mcp/mcp.json in your solution directory:

{
  "mcp": {
    "servers": {
      "crush-protocol": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@crush-protocol/mcp-client@latest"]
      }
    }
  }
}

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add via Perplexity → Settings → Connectors → Add Connector → Advanced. Server Name: crush-protocol

{
  "args": ["-y", "@crush-protocol/mcp-client@latest"],
  "command": "npx",
  "env": {}
}

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Add via Zencoder menu → Agent tools → Add custom MCP:

{
  "command": "npx",
  "args": ["-y", "@crush-protocol/mcp-client@latest"]
}

Qodo Gen chat → Connect more tools → + Add new MCP

{
  "mcpServers": {
    "crush-protocol": {
      "command": "npx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Bun:

{
  "mcpServers": {
    "crush-protocol": {
      "command": "bunx",
      "args": ["-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Deno:

{
  "mcpServers": {
    "crush-protocol": {
      "command": "deno",
      "args": [
        "run",
        "--allow-env",
        "--allow-net",
        "--allow-read",
        "--allow-write",
        "npm:@crush-protocol/mcp-client"
      ]
    }
  }
}

{
  "mcpServers": {
    "crush-protocol": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@crush-protocol/mcp-client@latest"]
    }
  }
}

Common Commands

npx -y @crush-protocol/mcp-client@latest setup --all
npx -y @crush-protocol/mcp-client@latest login
npx -y @crush-protocol/mcp-client@latest auth:status
npx -y @crush-protocol/mcp-client@latest doctor
npx -y @crush-protocol/mcp-client@latest logs:path
npx -y @crush-protocol/mcp-client@latest ping
npx -y @crush-protocol/mcp-client@latest tools:list
npx -y @crush-protocol/mcp-client@latest tools:call --name crush_status
npx -y @crush-protocol/mcp-client@latest trading:place-order --symbol BTC --side buy --notional-usdc 10
npx -y @crush-protocol/mcp-client@latest trading:spot-check --symbol BTC --notional-usdc 10
npx -y @crush-protocol/mcp-client@latest trading:cleanup-tpsl --symbol BTC

Live Order Safety

place_order is a two-step commit:

1. First call returns an order preview and pendingOrderId
2. Second call sends { "confirm": true, "pendingOrderId": "<id>" } in the same MCP session

The first call never places a live order. Use notionalUsdc for the amount to trade, e.g. 100 means approximately a 100 USDC order; MCP/wallet-service derive the Hyperliquid base size. Pending order ids expire after 60 seconds and are bound to the MCP session that created them. Preview blocks order rows below Hyperliquid's minimum notional. On confirm, confirmed / intentConfirmed means the user intent was confirmed; use executed, result.status, or result.results[] to determine whether the order actually executed.

For CLI users, prefer the dedicated trading commands instead of manually running CLI tools:call twice. tools:call is this package's CLI wrapper around the MCP tools/call protocol method, and it is a single-shot debugging helper: it opens a client, calls one tool, prints the result, and closes the client. The dedicated commands keep one MCP client/session alive across preview and confirm:

npx -y @crush-protocol/mcp-client@latest trading:place-order \
  --symbol BTC \
  --side buy \
  --notional-usdc 10

The command prints the preview and requires typing confirm before it submits the live order. Use --yes only for intentional automation. Automated submission requires both --yes and --i-understand-live-trading.

For preview/fill price verification, use:

npx -y @crush-protocol/mcp-client@latest trading:spot-check \
  --symbol BTC \
  --notional-usdc 10

This performs a buy market order followed by a reduce-only sell market order in the same MCP session, then reports estimatedFillPrice, executionLimitPrice, actual fill price, and diff percentages. Automated spot-check submission also requires both --yes and --i-understand-live-trading.

If a manual close/reduce leaves reduce-only TP/SL trigger orders open, clean them explicitly:

npx -y @crush-protocol/mcp-client@latest trading:cleanup-tpsl --symbol BTC

This calls cancel_reduce_only_tpsl_orders and only cancels reduce-only trigger orders with stop/take-profit semantics. Regular limit orders are skipped. Automated cleanup also requires both --yes and --i-understand-live-trading.

Workflow Catalog

Use crush_catalog when you want one compact MCP response with:

• recommended workflows
• safe read-only tools for allowlists
• write and sensitive tools that should stay gated

This is the lightest-weight way to orient an agent before it starts calling many discovery tools.

Reduce Permission Prompts

If you use Claude Code, you can auto-allow Crush's safe read-only tools and keep write actions gated.

Add this to ~/.claude/settings.json or .claude/settings.json in your project:

{
  "permissions": {
    "allow": [
      "mcp__crush-protocol__crush_status",
      "mcp__crush-protocol__crush_ch_list_tables",
      "mcp__crush-protocol__crush_ch_describe_table",
      "mcp__crush-protocol__crush_ch_data_freshness",
      "mcp__crush-protocol__crush_ch_list_indicators",
      "mcp__crush-protocol__crush_ch_find_data",
      "mcp__crush-protocol__crush_ch_run_query",
      "mcp__crush-protocol__crush_ch_query_candles",
      "mcp__crush-protocol__crush_ch_query_global_metrics",
      "mcp__crush-protocol__crush_ch_query_sentiment",
      "mcp__crush-protocol__crush_ch_query_token_list",
      "mcp__crush-protocol__crush_ch_query_token_market_info",
      "mcp__crush-protocol__crush_ch_query_unlock_events",
      "mcp__crush-protocol__crush_ch_search_news_feeds",
      "mcp__crush-protocol__crush_ch_search_twitter",
      "mcp__crush-protocol__crush_liq_query_heatmap",
      "mcp__crush-protocol__crush_liq_query_liquidations",
      "mcp__crush-protocol__crush_liq_query_risk",
      "mcp__crush-protocol__crush_liq_query_whales",
      "mcp__crush-protocol__get_available_tokens",
      "mcp__crush-protocol__get_signal_categories",
      "mcp__crush-protocol__get_signals_by_category",
      "mcp__crush-protocol__get_signal_operators_and_limits",
      "mcp__crush-protocol__get_backtest_config_schema",
      "mcp__crush-protocol__list_backtests",
      "mcp__crush-protocol__get_backtest",
      "mcp__crush-protocol__get_backtest_status",
      "mcp__crush-protocol__get_backtest_trades",
      "mcp__crush-protocol__get_backtest_portfolios",
      "mcp__crush-protocol__list_strategies",
      "mcp__crush-protocol__get_strategy",
      "mcp__crush-protocol__get_strategy_evaluations",
      "mcp__crush-protocol__get_strategy_logs",
      "mcp__crush-protocol__get_strategy_orders",
      "mcp__crush-protocol__validate_expression"
    ]
  }
}

Keep these tools gated because they mutate state or move capital:

• create_backtest
• create_strategy
• update_strategy
• delete_strategy
• toggle_strategy
• place_order
• cancel_order
• cancel_reduce_only_tpsl_orders

get_account_info, get_positions, and get_portfolio are read-only, but they expose sensitive balance data. Add them only if you are comfortable granting your agent unattended read access to account information.

Troubleshooting

| Problem | What to do | | --- | --- | | Tools do not appear after install | Restart the MCP host after setup | | Tools appear but fail with auth errors | Run npx -y @crush-protocol/mcp-client@latest login | | Crush was working before but now fails | Run npx -y @crush-protocol/mcp-client@latest doctor | | You want to confirm local auth state | Run npx -y @crush-protocol/mcp-client@latest auth:status | | Login completes but the host still asks you to sign in | Run npx -y @crush-protocol/mcp-client@latest auth:status, then doctor, then inspect the diagnostic log path from logs:path |

Local Diagnostic Logs

The client writes redacted JSONL diagnostics to:

~/.crush-mcp/logs/client.log

Use this command to print the exact path:

npx -y @crush-protocol/mcp-client@latest logs:path

The log records auth cache matches, token presence, OAuth redirects, callback results, connection failures, and proxy fallback decisions. It does not write raw access tokens, refresh tokens, authorization codes, or code verifiers.

When the host shows the login-required fallback after you already signed in, search the log for:

proxy.list_tools.login_required
proxy.call_tool.login_required
oauth_provider.redirect.blocked_non_interactive

Those events include a recentEvents array with the preceding client-side events, so you can see whether the proxy used a different server URL, missed the token cache, received a 401, or failed during refresh/reconnect.

Environment overrides:

CRUSH_MCP_LOG_DIR=/custom/dir
CRUSH_MCP_LOG_FILE=/custom/file.log
CRUSH_MCP_DISABLE_LOGS=1

License

Licensed under the MIT License.