mcp-pear

The Pear Protocol MCP server for Hyperliquid pair trading — connect Claude, Cursor, or any AI agent to on-chain perps: browse pair markets, read positions and portfolio, and (opt-in) execute pair trades.

Model Context Protocol (MCP) server for Pear Protocol. Gives Claude, or any MCP-compatible agent, access to markets, pair ratios, positions, orders, trade history, portfolio, and (v0.2) full trade execution on Hyperliquid.

v0.2 adds trade execution. Ten write tools (open, close, and adjust positions; manage leverage and risk; cancel orders) are off by default behind PEAR_TRADE_ENABLED=true. Pear signs server-side, so mcp-pear never holds private keys.

What is Pear Protocol?

Pear is a Hyperliquid-backed perps platform for pair markets: long one basket against another. Every pair has a live ratio that moves as the legs diverge. More at pearprotocol.io.

Tools

Public (no auth):

• get_health: API health and uptime
• list_markets: browse pair markets with filters and pagination
• get_active_markets: top gainers, losers, and highlighted pairs
• get_pair_ratio: current ratio, 24h change, and funding for a specific pair

Authenticated read:

• get_account_summary: your account header
• get_open_positions: your open positions with PnL
• get_open_orders: your open limit, TP, and SL orders
• get_twap_orders: your active TWAP orders
• get_trade_history: your closed trades with realized PnL
• get_portfolio: bucketed PnL across 1d, 1w, 1m, 1y, and all-time
• get_agent_wallet: the agent wallet Pear uses to sign your trades

Authenticated write (v0.2, gated behind PEAR_TRADE_ENABLED=true):

• create_agent_wallet: create the agent wallet
• open_position, close_position, close_all_positions: open and close pair positions
• adjust_position, adjust_leverage: change size or leverage on a live position
• set_risk_parameters: set or update TP and SL
• cancel_order, cancel_twap_order: cancel pending orders

Full parameter reference in Tool reference. See Trade execution (v0.2) for the gate and Hyperliquid funding rules.

Install

# Run directly
npx -y @marvelcodes/mcp-pear@latest

# Or install globally
pnpm install -g @marvelcodes/mcp-pear
mcp-pear

Pin @latest (or a specific version) in the npx spec. Plain npx @marvelcodes/mcp-pear can launch a stale cached version: npx prefers its local cache over the npm registry when the spec is unpinned, so after a new release lands you may still be running the old one. @latest re-resolves against the registry each launch; pin like @0.2.0 instead if you want a frozen version. Stuck on an old version after upgrading? Clear the npx cache: rm -rf ~/.npm/_npx (macOS/Linux).

Getting an API key

For the authenticated tools, mint a key:

npx -y @marvelcodes/mcp-pear@latest setup

The CLI opens a browser, asks you to sign once with your wallet, mints a Pear API key, and (optionally) writes PEAR_API_KEY and PEAR_ADDRESS to a .env. Copy those two values into your Claude Desktop config and restart Claude.

Already have a JWT from app.pear.garden? Skip setup and use JWT pass-through below.

Configuration

Three auth modes. mcp-pear uses the first one whose env vars are set, decided on the first authenticated call.

Mode 1: JWT pass-through (multi-tenant orchestrators)

For Telegram bots and other orchestrators that mint JWTs externally (Privy, EIP-712, or any Pear-supported flow). The JWT is opaque; mcp-pear never calls /auth/login.

When PEAR_JWT expires and no refresh token is set, authenticated tools return:

JWT expired; the orchestrator must mint a new one and restart mcp-pear.

See examples/telegram-bot-usage.ts for the orchestrator pattern.

Mode 2: API key + wallet address (single-user, Claude Desktop)

mcp-pear mints the JWT itself by calling POST /auth/login. Both fields are required: the OpenAPI spec needs address in the request body.

Public-only mode

The four public tools work without any auth env vars. Authenticated tools return a ConfigError naming the missing env var.

Common settings (optional)

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pear": {
      "command": "npx",
      "args": ["-y", "@marvelcodes/mcp-pear@latest"],
      "env": {
        "PEAR_API_KEY": "your-pear-api-key-here",
        "PEAR_ADDRESS": "0xYourWalletAddress"
      }
    }
  }
}

Restart Claude Desktop and ask: "Use Pear to show me the top active markets right now."

ADK-TS

import { McpToolset, StdioTransport } from "@iqai/adk";

const pearTools = new McpToolset({
	transport: new StdioTransport({
		command: "npx",
		args: ["-y", "@marvelcodes/mcp-pear@latest"],
		env: { PEAR_API_KEY: process.env.PEAR_API_KEY ?? "", PEAR_ADDRESS: process.env.PEAR_ADDRESS ?? "" },
	}),
});

await pearTools.connect();
const tools = await pearTools.listTools();

Full example in examples/adk-ts-usage.ts.

Tool reference

adjust_leverage

Change leverage (1-100x) on an existing Pear Protocol position. Higher leverage means greater liquidation risk for the same price move. WRITE: changes risk profile of a live position. Requires PEAR_TRADE_ENABLED=true.

adjust_position

Reduce or increase an existing Pear Protocol position's size by 1-100 percent. executionType: MARKET (immediate) or LIMIT (provide limitRatio). WRITE: changes exposure on a real trade. Requires PEAR_TRADE_ENABLED=true.

cancel_order

Cancel a pending Pear Protocol limit, take-profit, or stop-loss order by orderId. Does not affect already-filled portions. For TWAP orders, use cancel_twap_order. WRITE: cancels a live order. Requires PEAR_TRADE_ENABLED=true.

cancel_twap_order

Cancel a Pear Protocol TWAP (time-weighted average price) order and all of its remaining unfilled chunks. WRITE: cancels a live order. Requires PEAR_TRADE_ENABLED=true.

close_all_positions

Close every open Pear Protocol position with a single executionType (MARKET or TWAP). Returns a per-position result array with success/error. WRITE: executes real trades. Requires PEAR_TRADE_ENABLED=true.

close_position

Close one open Pear Protocol position by positionId. executionType: MARKET (immediate) or TWAP (spread over time; requires twapDuration in seconds). WRITE: executes a real trade. Requires PEAR_TRADE_ENABLED=true.

create_agent_wallet

Create a new Pear Protocol agent wallet for the authenticated user. The agent wallet is what Pear uses to sign Hyperliquid trades. After creation, the user MUST approve this wallet on Hyperliquid (the response message contains the approval instructions). WRITE: executes a state change. Requires PEAR_TRADE_ENABLED=true.

No parameters

get_account_summary

Get the authenticated user's Pear Protocol account summary: agent wallet address, total closed trades, pending trigger-order USD value, pending TWAP-chunk USD value, and last sync timestamp. Requires PEAR_API_KEY.

No parameters

get_active_markets

Get the most active Pear Protocol pair markets right now: current active pairs plus top gainers, top losers, highlighted pairs, and the user's watchlist. Use to see what's hot or as a starting point for narrowing into a specific pair.