mcp-pear

mcp-pear

Hyperliquid のペア取引に対応する Pear Protocol MCP サーバー — Claude、Cursor、または任意の AI エージェントをオンチェーンの無期限先物に接続し、ペア市場の閲覧、ポジションとポートフォリオの確認、および（オプトインで）ペア取引の実行ができます。

Pear Protocol 用の Model Context Protocol（MCP）サーバーです。Claude または MCP 対応のエージェントが、市場、ペア比率、ポジション、注文、取引履歴、ポートフォリオにアクセスできるほか、v0.2 では Hyperliquid での取引を完全に実行できます。

v0.2 で取引実行に対応しました。 10 個の書き込みツール（ポジションの新規作成、決済、調整、レバレッジとリスクの管理、注文のキャンセル）は、デフォルトで無効になっており、PEAR_TRADE_ENABLED=true で有効にします。Pear がサーバー側で署名するため、mcp-pear が秘密鍵を保持することはありません。

Pear Protocol とは？

Pear は Hyperliquid を基盤とする無期限先物プラットフォームで、ペア市場（一方のバスケットをもう一方に対してロングする取引）を提供します。各ペアには、構成要素の価格が乖離するにつれて変動するリアルタイムの比率があります。詳しくは pearprotocol.io をご覧ください。

ツール

公開（認証不要）：

• get_health：API の稼働状況と稼働時間
• list_markets：フィルターとページネーションを使ったペア市場の閲覧
• get_active_markets：値上がり上位、値下がり上位、注目のペア
• get_pair_ratio：指定したペアの現在の比率、24 時間の変動率、ファンディング

認証済み読み取り：

• get_account_summary：アカウントの概要
• get_open_positions：損益を含む保有中のポジション
• get_open_orders：保有中の指値注文、TP 注文、SL 注文
• get_twap_orders：有効な TWAP 注文
• get_trade_history：実現損益を含む決済済み取引
• get_portfolio：1 日、1 週間、1 か月、1 年、全期間ごとの損益
• get_agent_wallet：Pear が取引の署名に使用するエージェントウォレット

認証済み書き込み（v0.2、PEAR_TRADE_ENABLED=true で有効化）：

• create_agent_wallet：エージェントウォレットを作成
• open_position、close_position、close_all_positions：ペアポジションを新規作成および決済
• adjust_position、adjust_leverage：保有中のポジションのサイズまたはレバレッジを変更
• set_risk_parameters：TP と SL を設定または更新
• cancel_order、cancel_twap_order：保留中の注文をキャンセル

全パラメーターのリファレンスはツールリファレンスをご覧ください。有効化の設定と Hyperliquid の入金ルールについては、取引実行（v0.2）をご覧ください。

インストール

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

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

npx の指定には @latest（または特定のバージョン）を付けてください。 npx @marvelcodes/mcp-pear のようにバージョンを指定しない場合、古いキャッシュ済みバージョンが起動することがあります。指定がないと、npx は npm レジストリよりローカルキャッシュを優先するため、新しいリリースが公開された後も古いバージョンが実行される可能性があります。@latest を付けると起動ごとにレジストリで再解決されます。バージョンを固定したい場合は、代わりに @0.2.0 のように指定してください。アップグレード後も古いバージョンのままですか？ npx のキャッシュを消去してください：rm -rf ~/.npm/_npx（macOS/Linux）。

API キーの取得

認証が必要なツールを使うには、キーを発行します：

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

CLI がブラウザーを開き、ウォレットで一度署名するよう求めます。その後、Pear API キーを発行し、必要に応じて PEAR_API_KEY と PEAR_ADDRESS を .env に書き込みます。この 2 つの値を Claude Desktop の設定にコピーし、Claude を再起動してください。

app.pear.garden の JWT をすでにお持ちですか？ setup は省略し、以下の JWT パススルーを使用してください。

設定

認証モードは 3 種類あります。mcp-pear は環境変数が設定されている最初のモードを使用し、最初の認証済み呼び出し時に判定します。

モード 1：JWT パススルー（マルチテナントのオーケストレーター）

JWT を外部で発行する Telegram ボットなどのオーケストレーター向けです（Privy、EIP-712、または Pear がサポートする任意のフロー）。JWT は不透明な値であり、mcp-pear が /auth/login を呼び出すことはありません。

環境変数	必須	説明
PEAR_JWT	はい	事前に発行されたアクセストークンです。設定すると直接使用されます。JWT の有効期限が切れ、PEAR_REFRESH_TOKEN が設定されていない場合は、PEAR_API_KEY と PEAR_ADDRESS がフォールバックとして使用されます。
PEAR_REFRESH_TOKEN	いいえ	設定すると、セッション中に JWT の有効期限が切れた場合、mcp-pear が JWT を自動更新します（更新のたびにトークンがローテーションされます）。設定しない場合、オーケストレーター側で新しいトークンを発行し、サブプロセスを再起動する必要があります。

PEAR_JWT の有効期限が切れ、リフレッシュトークンが設定されていない場合、認証が必要なツールは次のエラーを返します。

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

オーケストレーターのパターンについては、examples/telegram-bot-usage.ts を参照してください。

モード 2：API キー＋ウォレットアドレス（シングルユーザー、Claude Desktop）

環境変数	必須	説明
PEAR_API_KEY	認証ツールで必要	Pear API キーです。
PEAR_ADDRESS	認証ツールで必要	API キーに紐付けられたウォレットアドレスです（0x...）。

mcp-pear は POST /auth/login を呼び出して JWT を自動発行します。OpenAPI 仕様ではリクエスト本文に address が必要なため、両方のフィールドが必須です。

パブリック専用モード

4 つのパブリックツールは、認証用の環境変数がなくても動作します。認証が必要なツールは、不足している環境変数の名前を示す ConfigError を返します。

共通設定（任意）

環境変数	デフォルト	説明
PEAR_API_BASE_URL	https://hl-v2.pearprotocol.io	Pear API ホストです。
PEAR_API_TIMEOUT_MS	10000	リクエストごとのタイムアウトです。
PEAR_CLIENT_ID	APITRADER	/auth/login に送信するクライアント識別子です。

Claude Desktop

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"
      }
    }
  }
}

Claude Desktop を再起動し、「Pear を使って、現在アクティブな市場の上位を表示してください」と尋ねます。

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();

完全な例は examples/adk-ts-usage.ts を参照してください。

ツールリファレンス

adjust_leverage

既存の Pear Protocol ポジションのレバレッジを変更します（1～100 倍）。レバレッジを高くすると、同じ価格変動でも清算リスクが高まります。書き込み操作：有効なポジションのリスクプロファイルを変更します。PEAR_TRADE_ENABLED=true が必要です。

パラメーター	型	必須	説明
positionId	string	はい
leverage	integer	はい

adjust_position

既存の Pear Protocol ポジションのサイズを 1～100 パーセント減らすか増やします。executionType は MARKET（即時）または LIMIT（limitRatio を指定）です。書き込み操作：実際の取引のエクスポージャーを変更します。PEAR_TRADE_ENABLED=true が必要です。

パラメーター	型	必須	説明
positionId	string	はい
adjustmentType	string	はい
adjustmentSize	integer	はい
executionType	string	はい
limitRatio	number
referralCode	string

cancel_order

orderId で Pear Protocol の未約定の指値注文、利確注文、または損切り注文をキャンセルします。すでに約定した部分には影響しません。TWAP 注文には cancel_twap_order を使用してください。書き込み操作：有効な注文をキャンセルします。PEAR_TRADE_ENABLED=true が必要です。

パラメーター	型	必須	説明
orderId	string	はい

cancel_twap_order

Pear Protocol の TWAP（時間加重平均価格）注文と、残っているすべての未約定分をキャンセルします。書き込み操作：有効な注文をキャンセルします。PEAR_TRADE_ENABLED=true が必要です。

パラメーター	型	必須	説明
orderId	string	はい

close_all_positions

単一の executionType（MARKET または TWAP）で、Pear Protocol のすべてのオープンポジションを決済します。ポジションごとの成功／エラーを含む結果の配列を返します。書き込み操作：実際の取引を実行します。PEAR_TRADE_ENABLED=true が必要です。

Parameter	Type	Required	Description
executionType	string	yes
twapDuration	number
twapIntervalSeconds	number
randomizeExecution	boolean
referralCode	string

close_position

positionId で指定した Pear Protocol のオープンポジションを1つ決済します。executionType は MARKET（即時）または TWAP（時間をかけて分散。秒単位の twapDuration が必要）です。書き込み操作：実際の取引を実行します。PEAR_TRADE_ENABLED=true が必要です。

Parameter	Type	Required	Description
positionId	string	yes
executionType	string	yes
twapDuration	number
twapIntervalSeconds	number
randomizeExecution	boolean
referralCode	string

create_agent_wallet

認証済みユーザー用の新しい Pear Protocol エージェントウォレットを作成します。エージェントウォレットは、Pear が Hyperliquid の取引に署名するために使用します。作成後、ユーザーは Hyperliquid でこのウォレットを必ず承認する必要があります（レスポンスメッセージに承認手順が記載されています）。書き込み操作：状態を変更します。PEAR_TRADE_ENABLED=true が必要です。

パラメーターはありません

get_account_summary

認証済みユーザーの Pear Protocol アカウント概要（エージェントウォレットのアドレス、決済済み取引の合計数、保留中のトリガー注文の USD 額、保留中の TWAP チャンクの USD 額、最終同期時刻）を取得します。PEAR_API_KEY が必要です。

パラメーターはありません

get_active_markets

現在、最も活発な Pear Protocol のペア市場を取得します。現在アクティブなペアに加え、値上がり率上位、値下がり率上位、注目ペア、ユーザーのウォッチリストが含まれます。注目の市場を確認したり、特定のペアに絞り込む際の出発点として使用します。

パラメーターはありません

get_agent_wallet

認証済みユーザーの Pear Protocol エージェントウォレットのアドレスを取得します。エージェントウォレットは、ユーザーに代わって Pear が Hyperliquid の取引に署名するために使用します。エージェントウォレットがまだ作成されていない場合は、アドレスが空または欠落した状態で返されます。作成するには create_agent_wallet を呼び出してください。

パラメーターはありません

get_health

Pear Protocol API のヘルス状態を確認します。サービスの状態、サーバーのタイムスタンプ、稼働時間（秒）を返します。他のツールを実行する前に、API に到達できることを確認するために使用します。

パラメーターはありません

get_open_orders

認証済みユーザーの Pear Protocol におけるオープン中の指値注文、利確注文、損切り注文を一覧表示します。各注文の ID、タイプ、ステータス、ペアの構成を返します。PEAR_API_KEY が必要です。

パラメーターはありません

get_open_positions

認証済みユーザーの Pear Protocol における現在のオープン中のペアポジションを一覧表示します。ポジション ID、エントリー比率、マーク比率、未実現損益、ロング／ショートの構成が含まれます。PEAR_API_KEY が必要です。

パラメーターはありません

get_pair_ratio

特定の Pear Protocol ペアの現在の比率（ロング／ショート構成の価格）を取得します。ロングとショートのアセット配列を渡します。比率、24時間の変動率、資金調達率を返します。対象のペアが決まっていて、最新の数値を確認したい場合に便利です。

Parameter	Type	Required	Description
longAssets	array	yes	ロング側のアセットシンボル（例：['BTC']）。
shortAssets	array	yes	ショート側のアセットシンボル。ロングのみのバスケットの場合は空の配列を渡します。

get_portfolio

認証済みユーザーの Pear Protocol におけるポートフォリオ全体の指標を取得します。過去1日／1週間／1か月／1年／全期間の期間別損益と、全体統計（取引総数、全期間の取引高、現在の未決済建玉、未実現損益）が含まれます。PEAR_API_KEY が必要です。

パラメーターはありません

get_trade_history

Pear Protocol で認証済みユーザーの最近の決済済み取引を、実現損益、エントリー／決済時の比率、ペア構成とともに取得します。日付範囲と件数を任意で指定できます。PEAR_API_KEY が必要です。

Parameter	Type	Required	Description
limit	integer		返す取引の最大件数です。デフォルトは 50 です。
startDate	string		ISO 8601 タイムスタンプまたはエポックミリ秒です。この時刻以降の取引のみを返します。
endDate	string		ISO 8601 タイムスタンプまたはエポックミリ秒です。この時刻以前の取引のみを返します。

get_twap_orders

Pear Protocol で認証済みユーザーの有効な TWAP（時間加重平均価格）注文を、分割注文の執行状況と約定の詳細とともに一覧表示します。PEAR_API_KEY が必要です。

パラメーターなし

list_markets

Pear Protocol のペア市場を、任意のフィルターとページネーションを使って閲覧します。各市場はロング／ショートの構成で、現在の比率、24 時間の変化、出来高、建玉、ファンディングが含まれます。取引可能な銘柄の確認や、searchText を使った特定のペアの検索に利用します。

Parameter	Type	Required	Description
search	string		市場名（`L:BTC
engine	string		執行エンジンで絞り込みます。
minVolume	number		米ドル換算の 24 時間最小出来高です。
change24h	number		24 時間の比率変化の最小値です（例：+5% の場合は 0.05）。
netFunding	number		ネットファンディングレートで絞り込みます。
sort	string		並べ替えキーです（例：'volume'、'change24h'）。
page	integer		ページ番号です（1 から始まります）。
pageSize	integer		1 ページあたりの結果数です。デフォルトは 20 です。

open_position

Pear Protocol で新しいペアポジションを開きます。executionType（MARKET / TRIGGER / TWAP / LADDER / TP / SL / SYNC）、leverage（1-100）、usdValue（≥1）、slippage（0.001-0.1）、およびロング／ショートの資産構成（{ asset, weight } の配列）を指定します。stopLoss/takeProfit と TWAP/TRIGGER/LADDER パラメーターを任意で設定できます。WRITE：実際の取引を執行します。PEAR_TRADE_ENABLED=true が必要です。

Parameter	Type	Required	Description
executionType	string	yes
leverage	integer	yes
usdValue	number	yes
slippage	number	yes
longAssets	array	yes
shortAssets	array	yes
triggerValue	number
triggerType	string
direction	string
twapDuration	number
twapIntervalSeconds	number
randomizeExecution	boolean
ladderConfig	object
stopLoss	unknown
takeProfit	unknown
referralCode	string

set_risk_parameters

既存の Pear Protocol ポジションのストップロス／テイクプロフィットを設定または更新します。各しきい値には、タイプ（'PRICE' または 'PERCENTAGE'）、値、任意のトレーリング用フィールドを指定します。フィールドをクリアするには null を渡し、変更しない場合は省略します。WRITE：有効なポジションのリスクパラメーターを変更します。PEAR_TRADE_ENABLED=true が必要です。

Parameter	Type	Required	Description
positionId	string	yes
stopLoss	unknown
takeProfit	unknown

開発

pnpm install
pnpm run build
pnpm test
pnpm run lint
pnpm run format

ライブスモークテスト：

PEAR_API_KEY=<real> pnpm test smoke

取引の実行（v0.2）

mcp-pear を読み取り専用から書き込み対応にする 10 個の新しいツールです。すべての書き込みツールはデフォルトで無効です。 PEAR_TRADE_ENABLED=true を設定すると有効になります（"true" との厳密な文字列一致が必要です。それ以外の値は、"True"、"1"、"yes" を含め、書き込みが無効のままになります）。Pear は作成したエージェントウォレットを使ってサーバー側で取引に署名するため、mcp-pear が取引の秘密鍵を保持することはありません。

ツール	種類	説明
get_agent_wallet	読み取り	Pear が取引の署名に使用するエージェントウォレットを取得します。
create_agent_wallet	書き込み	エージェントウォレットを作成します。作成後、Hyperliquid で承認してください（手順は応答メッセージに記載されています）。
open_position	書き込み	ペアポジションを開きます。MARKET、TRIGGER、TWAP、LADDER、TP、SL、SYNC に対応しています。
close_position	書き込み	ID を指定してポジションを 1 つ閉じます（MARKET または TWAP）。
close_all_positions	書き込み	1 つの実行タイプを指定して、開いているすべてのポジションを閉じます。
adjust_position	書き込み	ポジションサイズを 1〜100 パーセントの範囲で増減します。MARKET または LIMIT に対応しています。
adjust_leverage	書き込み	既存のポジションのレバレッジを 1〜100 倍に設定します。清算リスクを伴います。
set_risk_parameters	書き込み	既存のポジションの TP と SL を設定または更新します。
cancel_order	書き込み	保留中の指値注文、TP 注文、または SL 注文をキャンセルします。
cancel_twap_order	書き込み	TWAP 注文と残りの分割注文をキャンセルします。

環境変数	デフォルト	説明
PEAR_TRADE_ENABLED	未設定	書き込みツールを有効にするには、"true"（小文字、完全一致）を設定します。それ以外の場合は無効のままとなり、ゲートエラーが LLM に返されます。

PEAR_TRADE_ENABLED=true の場合、起動時に mcp-pear は stderr に [mcp-pear] PEAR_TRADE_ENABLED=true. Trade execution unlocked. を出力するため、オペレーターは書き込みが有効であることを確認できます。

資金と最小注文額

取引は Hyperliquid 上で実行され、ポジションの証拠金には Perps 残高が使用されます。初めて操作する際に注意が必要な点が 2 つあります。

• 最小注文額。 Hyperliquid は、想定元本が約 10 ドル未満の注文を拒否します。usdValue はポジションの米ドル建て想定元本です（証拠金 = usdValue / leverage）。そのため、片側のポジションでは usdValue が 10 以上である必要があります。ロングとショートのペアは別々の 2 件の注文となり、それぞれに 10 ドルの下限が適用されます（合計の想定元本は約 20 ドル以上です）。
• Spot と Perps の残高。 Hyperliquid にブリッジされた USDC（たとえば Circle CCTP 経由のもの）は、多くの場合 Spot 残高に入金されます。取引の前に Hyperliquid アプリで Perps に移動してください。移動しないと、open_position は証拠金不足で失敗します。

今後の予定

v0.3。 リアルタイムの市場およびポジション更新に対応する WebSocket ストリーミング。現物注文。Hyperliquid の candleSnapshot を使ったローソク足の生成。

よくある質問

Pear Protocol MCP サーバーとは何ですか？ mcp-pear は、Claude などの AI エージェントが Pear Protocol にアクセスできるようにする Model Context Protocol（MCP）サーバーです。Pear Protocol は、ペアトレード（一方のバスケットをロングし、もう一方をショートする取引）を行う Hyperliquid ベースのプラットフォームです。ペア市場やレシオの閲覧、ポジション・注文・ポートフォリオの確認、さらにオプションでペア取引を実行するためのツールを提供します。

Pear Protocol のトレーディングエージェントを構築するにはどうすればよいですか？ 任意の MCP クライアントから npx -y @marvelcodes/mcp-pear@latest を指定します。エージェントは、すぐに読み取り用ツール（市場、レシオ、ポジション、ポートフォリオ）を利用できます。取引を可能にするには、PEAR_TRADE_ENABLED=true を設定し、PEAR_API_KEY と PEAR_ADDRESS を追加します。これにより、open_position（MARKET／TRIGGER／TWAP／LADDER）、close_position、adjust_leverage、set_risk_parameters を呼び出せるようになります。接続例については、Claude Desktop と ADK-TS を参照してください。

Hyperliquid のペアトレードに対応していますか？ はい。Pear は Hyperliquid 上で稼働するため、すべてのペアポジションは Hyperliquid 上で実行されるロング／ショートの無期限先物取引です。mcp-pear は、ポジションの開始、調整、TP／SL の設定、決済という一連のライフサイクルに対応しています。

これは Pear Protocol 公式の MCP サーバーですか？ いいえ。mcp-pear は Pear の公開 API をラップする、独立したオープンソースのコミュニティプロジェクトです。Pear Protocol とは提携しておらず、同社の承認も受けていません。

免責事項

Pear Protocol とは提携していません。Pear の公開 API をラップする独立したプロジェクトです。v0.2 の取引実行ツールはデフォルトで無効になっており、オペレーターによる明示的なオプトイン（PEAR_TRADE_ENABLED=true）が必要です。署名は Pear のサーバー側で行われるため、mcp-pear が秘密鍵を保持することはありません。自己責任でご利用ください。保証はありません。

ライセンス

MIT。LICENSE を参照してください。