yellow-pro-mcp

English | 简体中文

MCP server + CLI exposing the yellow_pro exchange to AI agents — Claude Code, Codex CLI, Gemini CLI, Cursor, Hermes, OpenClaw, or any MCP client. Market data, account state, and (when explicitly enabled) trading.

Follows the same conventions as the official OKX / Bybit / Alpaca exchange MCP servers: local stdio process, credentials stay on your machine (environment variables or your MCP client's local config — never sent anywhere else), read-only by default, module filtering, built-in rate limiting, plus a CLI and an agent skill file for non-MCP agents.

Pairing onboarding preview

Pairing lets a Yellow Pro user connect a supported AI client without copying an API key or secret. Generate a short-lived pairing code in Yellow Pro, then run:

yellow-pro connect yp_pair_... --client claude-code

The command:

1. Redeems the one-time code through Yellow Pro Auth.

2. Verifies the returned read-only credential against the trading API.

3. Stores it in a client-specific file under ~/.yellow/connections/ with owner-only permissions.

4. Registers yellow-pro-mcp without putting secrets in the AI client's config.

Paired client registrations enable the MCP trading tool surface by default with YELLOW_PRO_ENABLE_TRADING=true. The exchange still enforces the credential's scopes, so read-only pairing codes can read data but receive insufficient_scope on trading calls.

Each client uses its own named profile and credential file. The profile defaults to the client name:

~/.yellow/connections/claude-code.json
~/.yellow/connections/codex.json
~/.yellow/connections/gemini.json
~/.yellow/connections/cursor.json
~/.yellow/connections/hermes.json
~/.yellow/connections/openclaw.json

Use --profile NAME when you need more than one connection for the same client. The scopes reported by connect and status are captured at pairing time; use get_api_key_permissions for live permissions after a UI change.

Restart the selected client after setup, then check the connection at any time:

yellow-pro status --profile claude-code

Remove the local credential with:

yellow-pro disconnect --profile claude-code

Local disconnect does not revoke the remote API key. Revoke it in Yellow Pro. The preview supports Claude Code, Codex CLI, Gemini CLI, Cursor, Hermes, OpenClaw, and read-only primary-account or sub-account credentials. Use --replace to replace an existing local connection.

Production endpoints are built in. For UAT or another test deployment, provide both service origins explicitly:

yellow-pro connect yp_pair_... --client claude-code \
  --auth-url https://auth.uat.yellow.pro.neodax.app \
  --api-url https://api.uat.yellow.pro.neodax.app

Related MCP server: FinClaw

One-liner install (for agents and humans)

Install from GitHub and register with Claude Code:

curl -fsSL -H 'Accept: application/vnd.github.raw+json' \
  'https://api.github.com/repos/layer-3/yellow-pro-mcp/contents/install.sh?ref=main' | bash && \
  YELLOW_PRO_API_KEY=... YELLOW_PRO_API_SECRET=... YELLOW_PRO_APP_SESSION_ID=... \
  yellow-pro setup claude-code

The installer checks Node.js >= 18, builds in a temporary directory, installs a packed tarball globally, and removes the temporary files. If the system npm prefix is not writable, it installs under ~/.local instead. Inspect install.sh before running it if your environment does not permit curl | bash.

Then register any MCP client with the installed server, for example Claude Code:

claude mcp add yellow_pro -s user \
  -e YELLOW_PRO_API_KEY=... -e YELLOW_PRO_API_SECRET=... -e YELLOW_PRO_APP_SESSION_ID=... \
  -- yellow-pro-mcp

The repo is public, so installation does not require GitHub credentials.

Multi-client setup — each registers the MCP server using your current YELLOW_PRO_* environment:

yellow-pro setup claude-code   # via `claude mcp add` (user scope)
yellow-pro setup codex         # via `codex mcp add`, falls back to config.toml snippet
yellow-pro setup gemini        # via `gemini mcp add` (user scope)
yellow-pro setup cursor        # atomically merges ~/.cursor/mcp.json
yellow-pro setup hermes        # via `hermes mcp add`, falls back to config.yaml snippet
yellow-pro setup openclaw      # via `openclaw mcp add`
yellow-pro setup json          # prints generic MCP JSON for any other client

npm i -g (or a local checkout: npm i -g /path/to/yellow_pro_mcp) gives you two commands: yellow-pro-mcp (MCP server) and yellow-pro (CLI).

Manual config (any MCP client)

# Codex CLI (~/.codex/config.toml)
[mcp_servers.yellow_pro]
command = "yellow-pro-mcp"
env = { YELLOW_PRO_API_KEY = "...", YELLOW_PRO_API_SECRET = "...", YELLOW_PRO_APP_SESSION_ID = "..." }

// OpenClaw (~/.openclaw/openclaw.json), Claude Desktop, Cursor, ...
{ "mcpServers": { "yellow_pro": { "command": "yellow-pro-mcp", "env": { "YELLOW_PRO_API_KEY": "..." } } } }

Agent skill (non-MCP agents)

skills/yellow-pro/SKILL.md teaches agents to use the yellow-pro CLI — copy it into your agent's skills directory (e.g. ~/.claude/skills/yellow-pro/).

Configuration

Trading tools are not registered unless YELLOW_PRO_ENABLE_TRADING=true. Market data tools work without credentials. An explicit YELLOW_PRO_BASE_URL takes precedence over sandbox mode.

Tools

• market: get_health, get_markets, get_ticker, get_orderbook, get_klines, get_funding_rate, get_funding_rate_history, get_networks, get_transfer_assets

• account: get_balance, get_open_orders, get_order_history, get_my_trades, get_positions, get_position_history, get_position_history_detail, get_spot_accounts, get_spot_account, get_perpetual_accounts, get_fee_schedule, get_fee_tier, get_market_fee_rate, get_transaction_history, get_funding_payments

• trading (opt-in): place_order, cancel_order, cancel_all_orders, close_positions, set_leverage, transfer

Markets use native ids: spot ETHUSDT, perpetual BTCUSDT-PERP. Amounts and prices are decimal strings. All results are raw exchange JSON.

place_order supports the same common single-order types for Spot and Perpetual:

• limit: requires price

• market: no price

• post_only: requires price and guarantees the order is maker-only

• trigger_limit (Stop Limit): requires both trigger_price and price

• trigger_market (Stop Market): requires trigger_price

Perpetual markets have a per-market position mode, listed under position_modes in get_perpetual_accounts. In HEDGE mode a market holds separate long and short legs and orders take direction long/short (defaulting from side, flipped by reduce_only). In ONE_WAY mode a market holds a single net position and the exchange requires direction: "both" — pass it explicitly, it is never inferred. Switching modes is only available in the yellow_pro web UI.

Perpetual trigger orders also accept the optional trigger_type value stop_loss or take_profit. Order queries return the classified conditional type, such as stop_limit, stop_loss, take_limit, or take_profit. cancel_order accepts either the request type (trigger_*) or these returned types and normalizes Spot cancellation.

Most list tools use the documented opt-in cursor protocol. Omit cursor for the first request; the MCP sends use_cursor=true. Pass the returned next_cursor to fetch the next page. page_size defaults to 50 and is capped at 100. Fill-level position history is cursor-native: its first request omits both cursor and use_cursor, and its documented page_size maximum is 500.

The yellow-pro CLI mirrors the same surface — yellow-pro --help.

Agent operating guidelines

The MCP server sends a compact version of these rules to clients as its default instructions:

• Call get_markets before trading to confirm market ids, precision, limits, leverage caps, and position modes.

• Amounts are decimal strings in the market's base asset, such as ETH for ETHUSDT or BTC for BTCUSDT-PERP. Prices are decimal strings in the quote asset, usually USDT.

• Check balances, open orders, and positions before any state-changing tool call.

• Spot and Perpetual balances are separate. Use transfer explicitly when funds need to move between Spot and Perps.

• Trading tools may be visible even when the credential is read-only. The exchange enforces API scopes. Scopes can change in the Yellow Pro UI without reconnecting, so call get_api_key_permissions before trading or after a UI permission change rather than relying on the scopes shown during onboarding.

• For tests, prefer small post_only or limit orders that rest on the book, then verify open orders and cancel/cleanup.

• Do not place market orders, close positions, or use bulk cancellation unless the user explicitly asks or confirms.

• For Perpetuals, HEDGE mode uses direction: "long" or "short". ONE_WAY mode requires direction: "both"; confirm the mode before using it.

Troubleshooting

MCP client shows no tools / server fails to connect

• Register through the CLI (yellow-pro setup claude-code, or claude mcp add directly) rather than editing config files by hand — Claude Code reads MCP config from ~/.claude.json, not ~/.claude/settings.json.

• The client spawns the server without loading your shell profile, so yellow-pro-mcp must be on the client's PATH. Check with which yellow-pro-mcp; if the installer printed a PATH hint, add that directory to your profile and restart the client.

• Restart the client after changing MCP config — servers connect at session start.

• Verify the server itself starts:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | yellow-pro-mcp

Authentication errors (invalid_api_key, invalid_timestamp)

• Private tools need all three of YELLOW_PRO_API_KEY, YELLOW_PRO_API_SECRET, YELLOW_PRO_APP_SESSION_ID, and they must match the environment you are hitting (YELLOW_PRO_SANDBOX=true keys do not work on production, and vice versa).

• invalid_timestamp means the machine clock is more than a few seconds off the exchange's — sync it (e.g. sudo sntp -sS time.apple.com on macOS, chrony/ntp on Linux).

Trading commands fail with "trading is disabled"

Set YELLOW_PRO_ENABLE_TRADING=true in the MCP client's env config. This is intentional — do not work around it by calling the REST API directly.

Risk warning

Trading involves risk of loss. Before use:

• Protect your credentials — grant API keys the minimum permissions needed and never commit them to source control.

• Test on staging first — run with YELLOW_PRO_SANDBOX=true against the staging environment before pointing at production.

• Trading is off by default — order/placement tools only exist when YELLOW_PRO_ENABLE_TRADING=true. Review every order the agent proposes before letting it through.

• You are in control — all actions are initiated by you or your AI assistant; the maintainers are not responsible for losses from agent behavior.

Development

npm install
npm test          # signature vectors (cross-checked against the reference impl) + tool registration
npm run build

The endpoint and request contracts follow the current yellow_pro API documentation. Not implemented on purpose: EIP-191/JWT auth and WebSocket streams.