mcp-pear

Name: mcp-pear
Author: MarvelNwachukwu

本地服务

github.com/MarvelNwachukwu金融数据115 周前更新

代码仓库

关于 mcp-pear

mcp-pear 是 Pear Protocol 的 MCP 服务，让 Claude、Cursor 等 AI Agent 查询 Hyperliquid 配对市场、账户和交易数据，并可在启用开关后执行交易。它通过 Pear 代为签名，不持有私钥。

主要功能

01浏览配对市场与比率
02查看持仓、订单和交易记录
03查询分时段组合盈亏
04开平仓并调整仓位与杠杆
05设置止盈止损及撤销订单

适用场景

01查看指定配对的实时比率与资金费率
02核对账户持仓、未完成订单和盈亏
03启用交易后调整仓位或关闭头寸

MCP 相关

向 MCP 客户端提供 Pear Protocol 市场、账户和交易工具。写入交易工具默认关闭，设置 PEAR_TRADE_ENABLED=true 后才可使用。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "marvelnwachukwu-mcp-pear": {
      "command": "npx",
      "args": [
        "-y",
        "@marvelcodes/mcp-pear"
      ],
      "env": {
        "PEAR_API_KEY": "<PEAR_API_KEY>",
        "PEAR_ADDRESS": "<PEAR_ADDRESS>",
        "PEAR_JWT": "<PEAR_JWT>",
        "PEAR_REFRESH_TOKEN": "<PEAR_REFRESH_TOKEN>",
        "PEAR_TRADE_ENABLED": "<PEAR_TRADE_ENABLED>"
      }
    }
  }
}

启动命令npx -y @marvelcodes/mcp-pear

需要配置的环境变量

PEAR_API_KEY密钥Pear API key for authenticated read/write tools (single-user mode). Public tools work without it.

PEAR_ADDRESSWallet address (0x...) bound to PEAR_API_KEY. Required alongside PEAR_API_KEY.

PEAR_JWT密钥Pre-minted Pear JWT for multi-tenant orchestrators (JWT pass-through mode). Used directly when set.

PEAR_REFRESH_TOKEN密钥Refresh token so the server refreshes an expired JWT itself instead of requiring a restart.

PEAR_TRADE_ENABLEDSet to 'true' to enable the write/trade-execution tools. Off by default.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@marvelcodes/mcp-pear0.2.2stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

mcp-pear

用于 Hyperliquid 配对交易的 Pear Protocol MCP 服务——将 Claude、Cursor 或任意 AI Agent 接入链上永续合约：浏览配对市场、读取持仓和投资组合，并可选择执行配对交易。

适用于 Pear Protocol 的 Model Context Protocol（MCP）服务。让 Claude 或任何兼容 MCP 的 Agent 访问市场、配对比率、持仓、订单、交易历史、投资组合，以及（v0.2）在 Hyperliquid 上完整执行交易。

v0.2 新增交易执行功能。 十个写入工具（开仓、平仓和调整持仓；管理杠杆和风险；取消订单）默认关闭，需通过 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：未完成的限价单、止盈单和止损单
get_twap_orders：当前有效的 TWAP 订单
get_trade_history：已平仓交易及已实现盈亏
get_portfolio：按 1d、1w、1m、1y 和全部时间范围统计的盈亏
get_agent_wallet：Pear 用于为你的交易签名的 Agent 钱包

经身份验证的写入工具（v0.2，需通过 PEAR_TRADE_ENABLED=true 启用）：

create_agent_wallet：创建 Agent 钱包
open_position、close_position、close_all_positions：开仓和平仓配对持仓
adjust_position、adjust_leverage：调整现有持仓的规模或杠杆
set_risk_parameters：设置或更新止盈和止损
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 registry，因此即使新版本已发布，你仍可能运行旧版本。每次启动时，@latest 都会从 registry 重新解析；如果想固定版本，可以改用 @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。将这两个值复制到 Claude Desktop 配置中，然后重启 Claude。

已有来自 app.pear.garden 的 JWT？跳过 setup，改用下文的 JWT 直通。

配置

有三种身份验证模式。mcp-pear 会在首次调用经身份验证的工具时，选择环境变量已设置的第一种模式。

模式 1：JWT 透传（多租户编排器）

适用于 Telegram 机器人和其他在外部签发 JWT 的编排器（Privy、EIP-712 或任何 Pear 支持的流程）。JWT 是不透明的；mcp-pear 不会调用 /auth/login。

环境变量	必需	描述
`PEAR_JWT`	是	预先签发的访问令牌。设置后会直接使用。如果 JWT 过期且未配置 `PEAR_REFRESH_TOKEN`，则会将 `PEAR_API_KEY` 和 `PEAR_ADDRESS` 用作回退。
`PEAR_REFRESH_TOKEN`	否	如果设置，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。

仅公开模式

四个公开工具无需任何身份验证环境变量即可使用。经过身份验证的工具会返回一个 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 并询问：“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();

完整示例请参阅 examples/adk-ts-usage.ts。

工具参考

`adjust_leverage`

调整现有 Pear Protocol 仓位的杠杆（1-100x）。对于相同的价格变动，杠杆越高，清算风险越大。写入操作：会改变现有仓位的风险状况。需要设置 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
`executionType`	string	是
`twapDuration`	number
`twapIntervalSeconds`	number
`randomizeExecution`	boolean
`referralCode`	string

`close_position`

根据 positionId 平掉一个未平仓的 Pear Protocol 仓位。executionType：MARKET（立即执行）或 TWAP（分时执行；需要以秒为单位的 twapDuration）。写操作：会执行真实交易。需要设置 PEAR_TRADE_ENABLED=true。

Parameter	Type	Required
`positionId`	string	是
`executionType`	string	是
`twapDuration`	number
`twapIntervalSeconds`	number
`randomizeExecution`	boolean
`referralCode`	string

`create_agent_wallet`

为通过身份验证的用户创建新的 Pear Protocol Agent 钱包。Pear 使用 Agent 钱包为 Hyperliquid 交易签名。创建后，用户必须在 Hyperliquid 上批准此钱包（响应消息中包含批准说明）。写操作：会更改状态。需要设置 PEAR_TRADE_ENABLED=true。

无参数

`get_account_summary`

获取通过身份验证的用户的 Pear Protocol 账户摘要：Agent 钱包地址、已平仓交易总数、待处理触发订单的 USD 价值、待处理 TWAP 分片的 USD 价值，以及上次同步时间戳。需要 PEAR_API_KEY。

无参数

`get_active_markets`

获取当前 Pear Protocol 中最活跃的交易对市场：当前活跃交易对、涨幅榜、跌幅榜、精选交易对，以及用户的关注列表。可用于了解当前热门交易对，或作为进一步筛选特定交易对的起点。

无参数

`get_agent_wallet`

获取通过身份验证的用户的 Pear Protocol Agent 钱包地址。Pear 使用 Agent 钱包代表用户为 Hyperliquid 交易签名。如果尚未创建 Agent 钱包，则返回空地址或不返回地址；调用 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	是	多头侧的资产符号（例如 ['BTC']）。
`shortAssets`	array	是	空头侧的资产符号。仅做多的组合请传入空数组。

`get_portfolio`

获取通过身份验证的用户在 Pear Protocol 上的完整投资组合指标：过去 1 天／1 周／1 个月／1 年／全部时间的分段盈亏，以及总体统计数据（交易总数、历史总交易量、当前未平仓头寸、未实现盈亏）。需要 PEAR_API_KEY。

无参数

`get_trade_history`

获取 Pear Protocol 上已通过身份验证的用户近期已平仓交易，包括已实现盈亏、入场/出场比率和配对构成。可选日期范围和数量限制。需要 PEAR_API_KEY。

参数	类型	描述
`limit`	integer	返回的交易数量上限。默认值为 50。
`startDate`	string	ISO 8601 时间戳或 epoch 毫秒。仅返回此时间及之后的交易。
`endDate`	string	ISO 8601 时间戳或 epoch 毫秒。仅返回此时间及之前的交易。

`get_twap_orders`

列出 Pear Protocol 上已通过身份验证的用户当前活跃的 TWAP（时间加权平均价格）订单，包括分批执行和成交详情。需要 PEAR_API_KEY。

无参数

`list_markets`

浏览 Pear Protocol 配对市场，可选筛选和分页。每个市场由多头/空头组合构成，包含当前比率、24 小时变化、交易量、未平仓量和资金费率。可用于发现可交易的市场，或使用 searchText 查找特定配对。

参数	类型	描述
`search`	string	在市场名称中进行全文搜索（组合键，例如 `L:BTC
`engine`	string	按执行引擎筛选。
`minVolume`	number	24 小时交易量最低值，单位为 USD。
`change24h`	number	24 小时比率变化最低值（例如，0.05 表示 +5%）。
`netFunding`	number	按净资金费率筛选。
`sort`	string	排序键（例如 'volume'、'change24h'）。
`page`	integer	页码（从 1 开始）。
`pageSize`	integer	每页结果数。默认值为 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 参数。写入操作：将执行真实交易。需要 PEAR_TRADE_ENABLED=true。

参数	类型	必填
`executionType`	string	是
`leverage`	integer	是
`usdValue`	number	是
`slippage`	number	是
`longAssets`	array	是
`shortAssets`	array	是
`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 可清除字段；省略字段则保持不变。写入操作：将更改实盘仓位的风险参数。需要 PEAR_TRADE_ENABLED=true。

参数	类型	必填
`positionId`	string	是
`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）

新增 10 个工具，让 mcp-pear 从只读扩展为支持写入。所有写入工具默认关闭。 设置 PEAR_TRADE_ENABLED=true 即可启用（仅严格匹配 "true"；任何其他值，包括 "True"、"1" 或 "yes"，都会使写入功能保持关闭）。Pear 通过你创建的 Agent 钱包在服务端为交易签名，因此 mcp-pear 绝不会持有用于交易的私钥。

工具	类型	描述
`get_agent_wallet`	读取	获取 Pear 用于为你的交易签名的 Agent 钱包。
`create_agent_wallet`	写入	创建 Agent 钱包。创建后，请在 Hyperliquid 上批准该钱包（响应消息中包含操作说明）。
`open_position`	写入	建立一组配对持仓。支持 MARKET、TRIGGER、TWAP、LADDER、TP、SL、SYNC。
`close_position`	写入	按 ID 平仓一个持仓（MARKET 或 TWAP）。
`close_all_positions`	写入	使用一种执行类型平掉所有未平仓持仓。
`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 会在启动时将 [mcp-pear] PEAR_TRADE_ENABLED=true. Trade execution unlocked. 记录到 stderr，以便运维人员确认写入功能已启用。

资金与最低要求

交易在 Hyperliquid 上执行，持仓保证金来自你的 Perps 余额。初次操作时有两个常见问题：

最低订单规模。 Hyperliquid 会拒绝名义价值低于约 $10 的订单。usdValue 是持仓的美元名义价值（保证金 = usdValue / leverage），因此单腿持仓的 usdValue 必须至少为 10。多头加空头的配对持仓包含两个独立订单，每个订单都受 $10 下限约束（总名义价值约为 $20 或更高）。
Spot 与 Perps 余额。 转入 Hyperliquid 的 USDC（例如通过 Circle CCTP）通常会进入你的 Spot 余额。交易前，请在 Hyperliquid 应用中将其转入 Perps，否则 open_position 会因保证金不足而失败。

后续计划

v0.3。 通过 WebSocket 实时推送市场和持仓更新。Spot 订单。根据 Hyperliquid candleSnapshot 合成蜡烛图。

常见问题

Pear Protocol MCP 服务是什么？ mcp-pear 是一个模型上下文协议（MCP）服务，可让 Claude 和其他 AI Agent 使用 Pear Protocol——一个由 Hyperliquid 支持的配对交易平台（做多一个篮子，同时做空另一个篮子）。它提供用于浏览配对市场和比率、查看持仓、订单和投资组合的工具，并可选择执行配对交易。

如何构建 Pear Protocol 交易 Agent？ 将任意 MCP 客户端指向 npx -y @marvelcodes/mcp-pear@latest。Agent 开箱即可使用读取工具（市场、比率、持仓、投资组合）。如需允许其交易，请设置 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 涵盖完整生命周期：开仓、调整、设置止盈／止损以及平仓。

这是 Pear Protocol 官方 MCP 服务吗？ 不是。mcp-pear 是一个独立的开源社区项目，用于封装 Pear 的公开 API。它与 Pear Protocol 无关联，也未获得其认可。

免责声明

与 Pear Protocol 无关联。它是对 Pear 公开 API 的独立封装。v0.2 版交易执行工具默认关闭，且需要操作员明确选择启用（PEAR_TRADE_ENABLED=true）。Pear 在服务器端签名，因此 mcp-pear 从不持有私钥。使用风险自负；不提供任何保证。

许可证

MIT。请参阅 LICENSE。

支持 Markdown

登录后评论

基本信息

作者: MarvelNwachukwu
语言: node
版本: 0.2.2
传输方式: stdio
收录时间: 2026年7月18日
最近更新: 15 周前
官方 Registry: io.github.MarvelNwachukwu/mcp-pear

报告问题

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

mcp-pear

关于 mcp-pear

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

mcp-pear

什么是 Pear Protocol？

工具

安装

获取 API 密钥

配置

模式 1：JWT 透传（多租户编排器）

模式 2：API 密钥 + 钱包地址（单用户、Claude Desktop）

仅公开模式

通用设置（可选）

Claude Desktop

ADK-TS

工具参考

adjust_leverage

adjust_position

cancel_order

cancel_twap_order

close_all_positions

close_position

create_agent_wallet

get_account_summary

get_active_markets

get_agent_wallet

get_health

get_open_orders

get_open_positions

get_pair_ratio

get_portfolio

get_trade_history

get_twap_orders

list_markets

open_position

set_risk_parameters

开发

交易执行（v0.2）

资金与最低要求

后续计划

常见问题

免责声明

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

`adjust_leverage`

`adjust_position`

`cancel_order`

`cancel_twap_order`

`close_all_positions`

`close_position`

`create_agent_wallet`

`get_account_summary`

`get_active_markets`

`get_agent_wallet`

`get_health`

`get_open_orders`

`get_open_positions`

`get_pair_ratio`

`get_portfolio`

`get_trade_history`

`get_twap_orders`

`list_markets`

`open_position`

`set_risk_parameters`