awesome-base-mcp

Node.js Model Context Protocol server for an autonomous agent wallet on Base. It supports native/ERC-20 payments, bounded ERC-20 allowances, Uniswap V3, Aerodrome, Aave V3, Morpho Blue, Hyperliquid, 0x and CoW Protocol.

License: CC0 1.0 (public domain) — see LICENSE · No warranty, real funds at risk — see DISCLAIMER

---

English

Features

• Wallet: wallet_get_address, wallet_get_balance, wallet_get_portfolio, wallet_get_allowances, wallet_pay, wallet_approve_token, wallet_revoke_allowance — portfolio research plus policy-governed payments, bounded approvals, and audited allowance revocation.
• DEX: uniswap_quote_v3 / uniswap_swap_v3, aerodrome_quote / aerodrome_swap, zeroex_quote / zeroex_swap, cow_quote / cow_place_order.
• Lending: Aave V3 (aave_supply, aave_withdraw, aave_borrow, aave_repay, plus account/reserve reads) and Morpho Blue (market discovery, supply/borrow/repay, collateral in/out).
• Contract inspection: contract_get_code returns all verified source files from Sourcify v2, then uses Base Blockscout as a fallback, with deployed bytecode and detected proxy implementations for independent honeypot review. It is read-only and is not a safety verdict.
• Risk research: contract_risk_report, token_risk_report, token_market_snapshot, transaction_simulate, and token_simulate_trade combine static code signals, liquidity observations, and read-only EVM simulations. Results are evidence, never a safety guarantee.
• Position safety: protocol_position_health combines Aave account health with current Morpho LLTV/oracle-based health calculations.
• Perps: hyperliquid_market, hyperliquid_account, hyperliquid_place_order, hyperliquid_cancel_order, hyperliquid_set_leverage, hyperliquid_transfer.
• Policy engine: WebUI-controlled execution switches, protocol switches, recipient/contract blacklists, per-asset caps, Hyperliquid coin/notional/leverage caps, pre-broadcast simulation, and a JSONL audit trail (audit/events.jsonl).

Setup

npm install
Copy-Item .env.example .env
# fill in AGENT_PRIVATE_KEY and BASE_RPC_URL — see comments in .env.example

Run over stdio (for VS Code / Claude Desktop):

npm run start:stdio

Run Streamable HTTP + policy WebUI on loopback:

$env:MCP_HTTP_BEARER_TOKEN = "replace-with-a-32-character-or-longer-random-secret"
npm run start:http

• MCP endpoint: http://127.0.0.1:5201/mcp (Bearer token required).
• WebUI: http://127.0.0.1:5202/ui/ — configure policy, then it writes .awesome-base-mcp.policy.json (git-ignored).
• VS Code users: .vscode/mcp.json starts the server over stdio; restart the MCP server after editing .env.

Security model

• The private key is only read from .env; it is never accepted through MCP tool input and never logged.
• .env, the policy file and audit/ are git-ignored. On POSIX the server enforces 0600 on sensitive files and rejects symlinked paths.
• Writes are submitted directly by the agent key — no interactive approval step. Use PAYMENT_LIMITS_JSON and the WebUI blacklists/caps to bound the blast radius.
• The bearer token is a wallet-control secret, not a user password. Keep both HTTP services on loopback; ALLOW_REMOTE_HTTP=true is only safe behind TLS and a trusted reverse proxy.

Testing

Two self-service integration suites live in tests/ and run against Base mainnet with your funded key — start with tiny amounts.

npm run test:read    # 24 read-only tools, costs nothing
npm run test:write   # full write cycle (swaps, Aave, Morpho, CoW fill, HL round-trip)

Known practical gotchas (learned while testing on mainnet):

• CoW on Base: allowance must go to the VaultRelayer 0xC92E8bdf79f0507f65a392b0ab4667716BFE0110 (differs from Ethereum mainnet).
• Morpho: repaying more than the outstanding debt panics — repay slightly less and accept dust debt; any open debt blocks withdrawing 100% of collateral.
• Aerodrome classic pools are thin — use a wide minimumAmountOut buffer and a long deadline.
• Free public RPCs rate-limit quickly; a free Alchemy/dRPC key is recommended.
• Hyperliquid "unified account" mode disables spot↔perp transfers (funds are shared automatically).

License

CC0 1.0 Universal — to the extent possible under law, the author waives all copyright and related rights. Use it, fork it, ship it.

Disclaimer

This software is provided as-is, without warranty of any kind. It moves real funds on mainnet with no interactive confirmation. You are solely responsible for every transaction. Read DISCLAIMER.md before use.

---

中文

功能

• 钱包:wallet_get_address、wallet_get_balance、wallet_get_portfolio、wallet_get_allowances、wallet_pay、wallet_approve_token、wallet_revoke_allowance —— 资产研究，以及受策略约束的转账、有界授权和可审计撤销授权。
• DEX:Uniswap V3、Aerodrome、0x、CoW Protocol 的报价与Swap工具。
• 借贷:Aave V3(supply/withdraw/borrow/repay 及账户、储备查询)与 Morpho Blue(市场发现、供款/借款/还款、抵押进出)。
• 合约检测:contract_get_code 优先返回 Sourcify v2 的全部已验证源码，未收录时回退到 Base Blockscout，并附带部署 bytecode 与识别到的代理实现，供 Agent 自行审查 honeypot 风险。该工具只读，返回结果不构成安全结论。
• 风险研究:contract_risk_report、token_risk_report、token_market_snapshot、transaction_simulate、token_simulate_trade 结合静态代码信号、流动性观察和只读 EVM 模拟；结果仅供判断，不构成安全保证。
• 仓位安全:protocol_position_health 汇总 Aave 健康度与基于当前 Morpho LLTV/预言机的健康度计算。
• 永续合约:Hyperliquid 行情、账户、下单、撤单、设置杠杆、资金划转。
• 策略引擎:WebUI 控制执行开关、协议开关、收款方/合约黑名单、单资产限额、Hyperliquid 币种/名义价值/杠杆上限、广播前模拟,以及 JSONL 审计日志(audit/events.jsonl)。

安装

npm install
Copy-Item .env.example .env
# 填写 AGENT_PRIVATE_KEY 和 BASE_RPC_URL —— 见 .env.example 内注释

以 stdio 运行(VS Code / Claude Desktop):

npm run start:stdio

以 Streamable HTTP + 策略 WebUI 运行(仅监听本地回环):

$env:MCP_HTTP_BEARER_TOKEN = "替换为至少32位随机字符串"
npm run start:http

• MCP 端点:http://127.0.0.1:5201/mcp(需 Bearer token)。
• WebUI:http://127.0.0.1:5202/ui/ —— 配置策略后写入 .awesome-base-mcp.policy.json(已被 git 忽略)。
• VS Code 用户:.vscode/mcp.json 已配置 stdio 启动;修改 .env 后需重启 MCP 服务器。

安全模型

• 私钥只从 .env 读取;绝不通过 MCP 工具入参接收,也绝不写日志。
• .env、策略文件、audit/ 均被 git 忽略。POSIX 上服务器对敏感文件强制 0600 权限并拒绝符号链接。
• 交易由 Agent 私钥直接广播——没有交互式确认步骤。请用 PAYMENT_LIMITS_JSON 和 WebUI 黑名单/限额控制风险敞口。
• Bearer token 是钱包控制凭据,不是用户密码。两个 HTTP 服务务必保持仅监听回环;ALLOW_REMOTE_HTTP=true 只有在 TLS + 可信反代之后才安全。

测试

两套自助集成测试在 tests/,直接跑在 Base 主网 + 你的真实私钥上——请从小额开始。

npm run test:read    # 24 个只读工具,零成本
npm run test:write   # 完整写入链路(swap、Aave、Morpho、CoW 真实成交、HL 开平仓)

主网实测踩过的坑:

• CoW(Base):授权必须给 VaultRelayer 0xC92E8bdf79f0507f65a392b0ab4667716BFE0110(与以太坊主网不同)。
• Morpho:还款超过欠款会直接 panic——要少还一点点并接受灰尘债;只要还有债务,就不能 100% 撤出抵押。
• Aerodrome 经典池很薄——minimumAmountOut 留大缓冲、deadline 给长。
• 免费公共 RPC 限流很快,建议申请免费的 Alchemy/dRPC key。
• Hyperliquid "统一账户"模式禁用现货↔合约划转(资金自动共享)。

许可证

CC0 1.0 Universal —— 在法律允许的最大范围内,作者放弃所有版权及相关权利。随便用、随便改、随便发布。

免责声明

本软件按原样提供,不附带任何形式的保证。它会在主网动用真实资金且没有交互式确认。每一笔交易的责任都由你自己承担。使用前务必阅读 DISCLAIMER.md。