VaultPilot MCP

VaultPilot MCP

面向 AI Agent 的自托管 DeFi。Agent 提出操作，由你在 Ledger 上批准——专为 Agent、MCP 和主机都可能遭到入侵的威胁模型而设计。只有设备可信；私钥永不离开设备。

读取链上持仓并在 Ethereum、Arbitrum、Polygon、Base、Optimism、TRON、Solana、Bitcoin 和 Litecoin 上准备交易。支持的协议：EVM 上的 Aave V3、Compound V3、Morpho Blue、Uniswap V3（兑换 + LP 操作）、Curve、Lido、EigenLayer、Rocket Pool、Safe（Gnosis）多签；Solana 上的 MarginFi、Kamino、Marinade、Jito；TRON 上的 SunSwap；此外还有 LiFi（EVM + EVM↔Solana + TRON + BTC 兑换/跨链桥接）和 Jupiter v6（Solana 兑换），并可选用 1inch 进行 EVM 报价交叉核验。EVM 通过 WalletConnect → Ledger Live 签名；TRON、Solana、Bitcoin 和 Litecoin 通过 USB HID 直接与设备通信并签名（Ledger Live 的 WalletConnect 桥接目前不支持这些命名空间）。支持 Claude Code（命令行/终端）、Cursor，以及通过 stdio 接入的任何兼容 MCP 的客户端。Claude.ai 聊天（网页 + 原生桌面应用）需要托管的 MCP 端点——已列入路线图，尚未发布。

Agent：请阅读 AGENTS.md。可粘贴到 Claude Code / Cursor / 任何兼容 MCP 的 Agent 中的一行提示词：

Install VaultPilot MCP from https://github.com/szhygulin/vaultpilot-mcp following AGENTS.md.

功能

• 投资组合 — 跨链余额、DeFi 持仓汇总、USD 总额、NFT 收藏（通过 Helius DAS 支持 EVM + Solana）、钱包级 PnL（mtd / ytd / 30d / 7d / 1d）、每日简报
• 持仓 — Aave、Compound、Morpho、Uniswap V3 LP、Curve、MarginFi、Kamino、Safe（Gnosis）多签；多协议健康因子提醒；清算风险模拟
• 质押 — Lido（质押 / 取消质押 / stETH↔wstETH 封装）+ EigenLayer + Rocket Pool（EVM）；TRON Stake 2.0（冻结 / 解冻 / 投票 / 领取）；Solana（Marinade、Jito、原生委托/停用/提取）
• 兑换 + 跨链桥接 — LiFi（EVM + EVM↔Solana + TRON + BTC 路由，可选 1inch 交叉核验）、Jupiter v6（Solana）、直接使用 Uniswap V3、Curve、SunSwap（TRON）
• 执行 — 为所有支持的协议以及原生币/代币转账准备和签名，支持 ERC-20 授权 + 撤销、WETH 封装/解封，以及用于执行任意已验证合约调用的 prepare_custom_call 备用接口。Solana 转账使用每个钱包独立的 durable-nonce 账户，避免 Ledger 审核与约 60 秒的区块哈希有效期竞争；每次 Solana 准备操作都会通过 simulateTransaction 门控，确保程序级回滚在准备阶段而非广播时失败。
• Bitcoin + Litecoin — 原生隔离见证 + taproot 转账、BIP-125 RBF 手续费加价、PSBT 多签（合并 / 签名 / 完成）、BIP-137 消息签名、mempool.space 手续费估算；可选使用 Bitcoin Core / Litecoin Core RPC 进行取证级链上读取（分叉、内存池统计、手续费百分位数）
• 安全 — 合约验证、可升级性检查、特权角色枚举、由 DefiLlama 提供支持的风险评分、设备上的 Ledger 认证 + 固件版本锁定、用于二次 LLM 字节与意图交叉核验的 verify_tx_decode、签名的磁盘联系人/地址簿
• 实用工具 — ENS 解析、符号→合约 resolve_token 注册表、代币余额、授权额度枚举、交易状态、事后解码 explain_tx、跨借贷 + LST 适配器的 compare_yields
• 演示模式 — 精选 persona（whale / defi-degen / stable-saver / staking-maxi），首次体验无需 RPC 密钥 / Ledger / 配置文件

安全模型

失陷模型：AI Agent、MCP 服务和主机都可能由攻击者控制。只有 Ledger 可信。每笔交易都会在各层间进行密码学绑定，因此任何篡改——替换收款方、重写兑换路由、夹带授权——都会在签名前显示于设备屏幕上，确保篡改可被发现。

user-intent ──► agent ──► MCP server ──► WalletConnect / USB-HID ──► Ledger Live / host ──► Ledger device

纵深防御：服务端 prepare↔send 指纹、独立的 4byte.directory 选择器检查、Agent 端 ABI 解码与签名前哈希重算、设备端明文签名或盲签哈希匹配、WalletConnect 会话主题交叉检查、previewToken/userDecision 门控，以及针对高价值流程使用 get_verification_artifact 进行二次大模型交叉验证。完整威胁模型、防御措施表、剩余风险和验证方案，请参阅 SECURITY.md。

Agent 端加固（强烈建议）

MCP 自身的 CHECKS PERFORMED 指令可能会被失陷的服务端悄然省略。请安装配套的 vaultpilot-security-skill，让 Agent 无论 MCP 如何声明，都能强制执行密码学完整性不变量——字节解码、分发目标允许列表、哈希重算、链必须明确指定、跨链桥收款方交叉检查、授权类别提示、硬触发操作必须进行二次大模型验证、集合级意图验证，以及持久绑定的真实数据源：

git clone https://github.com/szhygulin/vaultpilot-security-skill.git \
  ~/.claude/skills/vaultpilot-preflight

重启 Claude Code。技能文件的 SHA-256 值已固定在服务端源代码中；磁盘篡改或插件冲突会显示为 integrity check FAILED。

对话式 /setup（可选）

如需通过聊天引导完成初始设置，并检测当前配置、仅收集实际需要的密钥，请安装配套的 vaultpilot-setup-skill：

git clone https://github.com/szhygulin/vaultpilot-setup-skill.git \
  ~/.claude/skills/vaultpilot-setup

重启，然后输入 /setup。

支持的链

EVM — Ethereum、Arbitrum、Polygon、Base、Optimism。Lido 在 Ethereum + Arbitrum 上提供读取功能，写入功能仅支持 Ethereum。EigenLayer + Morpho Blue + Rocket Pool 仅支持 Ethereum。Compound V3 + Aave V3 + Uniswap V3 + LiFi + Safe 多签覆盖全部五条链；各协议的地址覆盖范围有所不同——如果某个协议未部署，读取器会直接跳过。

TRON — TRX + 原生 TRC-20 稳定币（USDT、USDC、USDD、TUSD）；Stake 2.0 冻结/解冻/提取到期解冻 + 投票奖励领取；SunSwap（同链 TRX↔TRC-20 兑换）；由 LiFi 路由的 TRON↔EVM 跨链桥接。无借贷/LP（未部署 Aave/Compound/Morpho/Uniswap）。每个会话配对一次，通过 pair_ledger_tron。

Solana — SOL + SPL 余额、MarginFi + Kamino 借贷、Marinade / Jito / 原生质押账户读取及 SOL 等值估值、Jupiter v6 报价、Helius DAS NFT 投资组合。写入操作包括 SOL/SPL 转账、MarginFi + Kamino 存入/提取/借款/还款、Jupiter 兑换、Marinade 质押 + 立即取消质押、Jito 质押池存入、原生 SOL 委托/停用/提取，以及由 LiFi 路由的 EVM↔Solana 跨链桥接。每个钱包的持久 nonce 账户（约 0.00144 SOL 租金，可回收）可在 Ledger 审核期间防止发送操作因区块哈希过期而失败（prepare_solana_nonce_init / _close）。SPL / MarginFi / Kamino / Jupiter / Jito 使用消息哈希盲签——请在 Solana 应用的设置中启用 Allow blind signing；SOL 原生转账使用明文签名。每个会话配对一次，通过 pair_ledger_solana。

Bitcoin + Litecoin — 通过 Esplora（mempool.space / litecoinspace.org）读取余额、UTXO、手续费估算和交易历史。支持原生隔离见证 + taproot 发送、BIP-125 RBF 手续费加价、多签 PSBT（合并 / 签名 / 最终化）、BIP-137 消息签名，以及由 LiFi 路由的 BTC→EVM/Solana 兑换。可选的 Bitcoin Core / Litecoin Core JSON-RPC 可启用 Esplora 无法提供的取证工具（链尖端、区块统计、内存池摘要）——安装说明请参见 INSTALL.md §9。通过 pair_ledger_btc / pair_ledger_ltc 配对一次。

Ledger Live 的 WalletConnect 桥接不支持 tron: 命名空间（已于 2026-04-14 验证），也不提供 Solana 账户（已于 2026-04-23 验证），且不提供 BTC/LTC 命名空间，因此这些路径使用 USB HID。若某个协议未部署在相应链上，读取器会直接跳过。

路线图

ROADMAP.md。

工具

约 190 个工具，分为读取 / 配对 Ledger / 准备 / 签名+发送 / 验证 / 诊断等类别。以下为重点介绍；每个工具均有 Zod 输入架构和详细说明——请查询 MCP 服务的 tools/list 获取规范工具列表。

投资组合 + 持仓（只读）：

• get_portfolio_summary、get_portfolio_diff、get_pnl_summary、get_daily_briefing — 跨链 USD 汇总；可选的 tronAddress / solanaAddress 会将相应链纳入汇总
• get_lending_positions（Aave）、get_compound_positions、get_morpho_positions、get_marginfi_positions、get_kamino_positions、get_curve_positions、get_safe_positions — 按协议列出持仓和健康因子
• get_lp_positions — Uniswap V3 流动性提供者（LP）持仓及无常损失（IL）估算
• get_staking_positions、get_staking_rewards、estimate_staking_yield — Lido + EigenLayer + Rocket Pool
• get_solana_staking_positions — Marinade + Jito + 原生质押账户枚举，包含激活状态和 SOL 等值估值
• get_tron_staking、list_tron_witnesses — TRON Stake 2.0 状态 + SR 列表
• get_nft_portfolio（EVM + Solana DAS）、get_nft_collection、get_nft_history、get_nft_listings（EVM）
• get_btc_balance / _balances / _account_balance / _multisig_balance / _multisig_utxos / _tx_history / _fee_estimates、get_ltc_balance — 通过 Esplora 查询 BTC + LTC
• get_compound_market_info — 无需钱包的 Comet 快照
• get_health_alerts、simulate_position_change — 多协议清算风险工具
• compare_yields — 对 Aave / Compound / Morpho / Marinade / Jito / Kamino-lend / MarginFi 的借贷 APR 排名
• get_marginfi_diagnostics — 列出打包的 SDK 跳过的银行，并说明根本原因

代币、价格、历史记录：

• get_token_balance、get_token_price、get_token_metadata、get_token_allowances、get_coin_price — 查询 EVM/TRON/Solana 上的余额 + DefiLlama 价格；get_token_metadata 可检测 EIP-1967 代理
• get_transaction_history — 合并的交易读取器（外部 / ERC-20 / 内部 / Solana program_interaction），包含通过 4byte 解码的方法 + 历史 USD 价格
• get_transaction_status — 通过哈希轮询交易是否已纳入区块
• explain_tx — 对历史交易进行事后解码
• resolve_token、resolve_ens_name、reverse_resolve_ens

链上取证读取（需要 Bitcoin/Litecoin Core RPC）：

• get_btc_block_tip / _block_stats / _blocks_recent / _chain_tips / _mempool_summary，以及对应的 get_ltc_*
• build_incident_report、get_market_incident_status — 扫描 Compound/Aave 暂停状态 + 利用率，并汇总 BTC/LTC 链尖端 / 内存池异常信息

报价 + 安全信号：

• get_swap_quote（LiFi，EVM）、get_solana_swap_quote（Jupiter v6）
• check_contract_security、check_permission_risks、get_protocol_risk_score、get_contract_abi、read_contract
• simulate_transaction — EVM eth_call 预览（Solana 对应功能在 preview_solana_send 中运行）
• verify_tx_decode、get_verification_artifact、get_tx_verification — 第二个 LLM 交叉验证 + 15 分钟 TTL 句柄重新发送（详情）

诊断：

• get_solana_setup_status — 探测 nonce + MarginFi 账户 PDA
• get_vaultpilot_config_status — 本地配置诊断（RPC 来源、密钥是否存在、配对账户数量、WC 主题后缀、技能状态）。仅包含布尔值 / 数量，不包含秘密值。
• get_ledger_device_info、get_ledger_status、verify_ledger_attestation / _firmware / _live_codesign — 设备 + 会话发现、设备端证明、固件版本固定

联系人 + 只读共享：

• add_contact / remove_contact / list_contacts / verify_contacts — 本地 Ledger 签名的地址簿，位于 ~/.vaultpilot-mcp/contacts.json
• generate_readonly_link / import_readonly_token / list_readonly_invites / revoke_readonly_invite — 创建权限范围受限的只读投资组合链接
• share_strategy / import_strategy — 匿名化的投资组合快照

执行（Ledger 签名）：

• pair_ledger_live（EVM/WC）、pair_ledger_tron / _solana / _btc / _ltc（USB HID）
• prepare_aave_*、prepare_compound_*、prepare_morpho_* — EVM 借贷（供应 / 借款 / 提取 / 还款）
• prepare_lido_stake / _unstake / _wrap / _unwrap（stETH↔wstETH）、prepare_eigenlayer_deposit、prepare_rocketpool_stake / _unstake
• prepare_swap（LiFi）、prepare_native_send、prepare_token_send、prepare_token_approve、prepare_revoke_approval、prepare_weth_unwrap
• prepare_uniswap_swap — 直接进行 V3 兑换，仅限同一链，自动选择 100/500/3000/10000 bps 费率档位。仅当用户指定 Uniswap 时使用；否则优先使用 LiFi
• prepare_uniswap_v3_mint / _increase_liquidity / _decrease_liquidity / _collect / _burn / _rebalance — 完整的 LP 操作动词集
• prepare_curve_swap、prepare_curve_add_liquidity
• prepare_safe_tx_propose / _approve / _execute、submit_safe_tx_signature — Safe 多签提案流程
• prepare_custom_call — 任意已验证合约调用的后备方案（需通过 acknowledgeNonProtocolTarget: true 门控；按设计绕过规范分发允许列表）
• prepare_tron_* — 原生代币 + TRC-20 转账、WithdrawBalance、Stake 2.0、投票、领取奖励、TRC-20 授权、LiFi 兑换、SunSwap 兑换（prepare_sunswap_swap）
• prepare_solana_nonce_init / _close — 一次性持久 nonce PDA 设置 / 拆除
• prepare_solana_native_send、_spl_send（自动包含 ATA 创建）、prepare_solana_swap（Jupiter）、prepare_solana_lifi_swap
• prepare_marginfi_init、_supply、_withdraw、_borrow、_repay
• prepare_kamino_init_user、_supply、_withdraw、_borrow、_repay
• prepare_marinade_stake / _unstake_immediate（会收取费用；延迟的 unstake-ticket 路径暂不支持）、prepare_jito_stake（仅支持质押 — 暂不支持解除质押）、list_solana_validators
• prepare_native_stake_delegate / _deactivate / _withdraw — 原生 SOL 质押
• prepare_btc_send、prepare_btc_rbf_bump、prepare_btc_multisig_send、register_btc_multisig_wallet / unregister_btc_multisig_wallet、combine_btc_psbts、sign_btc_multisig_psbt、finalize_btc_psbt、sign_message_btc、prepare_btc_lifi_swap、rescan_btc_account
• prepare_litecoin_native_send、sign_message_ltc、rescan_ltc_account
• preview_send（EVM）— 固定 Gas，生成 LEDGER BLIND-SIGN HASH 以供预匹配，并创建 previewToken；每次 EVM prepare_* 与 send_transaction 之间都必须调用
• preview_solana_send — 固定 nonce/blockhash，计算用于设备端匹配的 Message Hash，运行模拟，并生成 CHECKS PERFORMED；每次 prepare_solana_* 与 send_transaction 之间都必须调用
• send_transaction — 转发至 Ledger（EVM 通过 WC，TRON/Solana/BTC/LTC 通过 USB HID）

Meta：

• request_capability — 提交缺失功能的 GitHub issue。默认返回预填充的 URL（不会自动提交）；每小时限 3 次
• set_etherscan_api_key、set_helius_api_key、set_demo_wallet、exit_demo_mode、get_demo_wallet、get_update_command — 运行时控制项

要求

• Node.js ≥ 18.17
• 零配置读取： PublicNode（EVM）+ Solana 公共主网 — 有速率限制，但足以满足首次使用和轻量使用需求。
• 实际使用： 通过环境变量或 vaultpilot-mcp setup 配置自定义 RPC（Infura / Alchemy / Helius / QuickNode / Triton）。
• 可选密钥（按需提示）：Etherscan、1inch（启用兑换报价比较）、WalletConnect 项目 ID（EVM Ledger 签名必需）、TronGrid（提高约 15 次请求/分钟的匿名上限）。
• TRON / Solana 签名： 通过 USB HID 连接已安装 Tron / Solana 应用的 Ledger。Linux：安装 Ledger 的 udev 规则（vaultpilot-mcp setup 会打印确切的一行命令）。Debian/Ubuntu 还需要运行 sudo apt install libudev-dev build-essential，以便编译 node-hid。

安装

三种方式——完整说明、MCP 客户端接入、Gatekeeper / SmartScreen 处理、更新 / 卸载，请参阅 INSTALL.md。

方式	简要说明
打包二进制文件（无需 Node）	从最新版本下载，运行 chmod +x，再执行 <binary> setup。
通过 npm 安装	npm install -g vaultpilot-mcp && vaultpilot-mcp setup
从源码安装	git clone https://github.com/szhygulin/vaultpilot-mcp.git && cd vaultpilot-mcp && npm install --legacy-peer-deps && npm run build && npm run setup

设置

npm run setup

选择 RPC 提供商，验证密钥，可选配对 Ledger Live，并写入 ~/.vaultpilot-mcp/config.json。环境变量会覆盖配置。

演示模式

无需 RPC 密钥、Ledger 配对或向导即可试用：

claude mcp add vaultpilot-mcp --env VAULTPILOT_DEMO=true -- npx -y vaultpilot-mcp

--demo 是等效的命令行标志；显式设置的环境变量优先，因此 VAULTPILOT_DEMO=false 可确定性地退出演示模式，适用于脚本调用。

• 读取操作会使用真实 RPC；每个钱包都是精心挑选的公开人物设定（whale、defi-degen、stable-saver、staking-maxi）。
• send_transaction 会返回一个模拟封装：未签名交易会通过 simulate_transaction 进行模拟以检测回滚，不会签名，也不会广播。
• pair_ledger_*、request_capability、sign_message_* 会被直接拒绝。未选择人物设定时，签名类工具会返回结构化错误，并指向 set_demo_wallet。
• 前置条件为状态变更的多步骤流程（例如 prepare_solana_nonce_init → marinade_stake）无法端到端演练，因为模拟发送不会更改链上状态。MCP 检测到 Agent 循环陷阱时，会显示一次性提示。

get_demo_wallet 会列出人物设定、地址和 rehearsableFlows。set_demo_wallet({ persona }) 可激活一个人物设定。状态仅在进程内有效。exit_demo_mode 会返回永久设置的交接指南。演示模式是初次体验的脚手架，而非沙盒——没有虚拟链覆盖层。

针对多工具并发调用时的 Solana RPC 限流，可在运行时注入 Helius 密钥：set_helius_api_key({ key })。演示模式在出现 10 次公共 RPC 限流错误后会主动提示。

与 Claude Code（CLI）/ Cursor / Claude Desktop 搭配使用

vaultpilot-mcp setup 会检测已安装的客户端，并为每个客户端注册 vaultpilot-mcp（现有配置会备份到 <file>.vaultpilot.bak）。系统会跳过项目级 / 工作区级配置，因为向导会从任意 CWD 运行。如需手动接入或查看各客户端的配置路径，请参阅 INSTALL.md §5。

Claude.ai 聊天——限制。 使用向导安装的本地 stdio MCP 可以顺利注册到 Claude.ai 原生桌面应用，但宿主环境的出站 HTTP 允许列表会阻止链上 RPC 提供商（PublicNode、公共 Solana 主网、Alchemy、Helius 等）。MCP 可以初始化并处理工具调用，但所有访问外部 RPC 的读取操作都会失败，并返回 403 / “Host not in allowlist”。在 Claude.ai 云沙盒中运行的 Claude Code 也有同样的问题。目前可用：终端中的 Claude Code CLI、Cursor、运行在出站 HTTP 不受限制的主机上的 Claude Desktop。未来：托管 MCP 端点（路线图，尚未发布）将为 Claude.ai 聊天提供不受网络限制的后端；TRON / Solana / Bitcoin / Litecoin USB-HID 签名需要本地 Ledger，因此无论如何都只能通过终端 CLI / Cursor 使用。

环境变量

如果 ~/.vaultpilot-mcp/config.json 中配置了对应字段，则以下变量均为可选；环境变量优先。

• ETHEREUM_RPC_URL、ARBITRUM_RPC_URL、POLYGON_RPC_URL、BASE_RPC_URL、SOLANA_RPC_URL — 自定义 RPC 端点
• RPC_PROVIDER（infura | alchemy）+ RPC_API_KEY — 自定义 URL 的替代方案
• ETHERSCAN_API_KEY、ONEINCH_API_KEY、TRON_API_KEY、WALLETCONNECT_PROJECT_ID
• RPC_BATCH=1 — 启用 JSON-RPC 批处理（默认关闭；许多公共端点无法正确处理批量 POST 请求）
• VAULTPILOT_ALLOW_INSECURE_RPC=1 — 跳过 https／私有 IP RPC 检查（仅限本地 anvil/hardhat）
• VAULTPILOT_FEEDBACK_ENDPOINT — 可选的 https 代理，用于处理 request_capability 直接 POST 请求。客户端不会进行身份验证；代理必须进行身份验证。
• VAULTPILOT_SKILL_MARKER_PATH — 不显示技能预检提示（主动选择启用此项的只读用户）
• VAULTPILOT_DISABLE_SKILL_AUTOINSTALL=1 — 跳过首次运行时延迟执行的伴随技能 git clone（适用于隔离环境／无外网连接）
• VAULTPILOT_DEMO=true — 启用演示模式；仅接受字面值 "true"，其他值均会被拒绝
• VAULTPILOT_DISABLE_UPDATE_CHECK=1 — 跳过每个会话一次的 registry.npmjs.org 更新检查（适用于隔离环境）

开发

npm run dev      # tsc --watch
npm test         # vitest run
npm run test:watch

贡献

欢迎提交 PR。你第一次提交 PR 时，CLA Assistant 机器人会要求你签署贡献者许可协议——签署一次即可涵盖今后的所有 PR。CLA 授予项目重新许可你的贡献的权利；若未签署，2030 年 BUSL-1.1 → Apache 2.0 的自动转换将无法进行。仓库所有者和 Dependabot 不受此要求限制。

许可证

Business Source License 1.1——详见 LICENSE。

• 个人自托管使用免费，包括代表自己进行收益、兑换、借贷和质押。
• 组织内部使用免费。
• 托管服务和嵌入式再分发需要商业许可证——请提交 issue 或联系维护者。
• **将于 2030-04-26 自动转换为 Apache 2.0。**每个版本的限制将在发布四年后失效。
• **版本 ≤ 0.8.2 仍采用 MIT 许可证。**许可证变更适用于 v0.9.0 及后续版本。