foundry-zksync

foundry-zksync-mcp

一个 MCP（Model Context Protocol）服务，可向 Claude 等 AI 助手提供 foundry-zksync CLI 工具。

工具

工具	描述
init	forge init，自动配置 zkSync
compile	forge build --zksync
test	forge test --zksync，支持过滤和详细程度选项
run_script	forge script --zksync，支持广播、发送者和慢速模式
deploy	forge create --zksync，支持结构化输出解析
verify	forge verify-contract --zksync（Etherscan 和 zkSync Explorer）
install	使用 forge install 管理依赖项
clean	使用 forge clean 移除构建产物
gas_report	使用 forge test --gas-report 分析 Gas 用量
snapshot	使用 forge snapshot 进行 Gas 基准测试
read_foundry_toml	读取并检查项目配置
explain	将错误/日志与 zkSync 常见问题知识库进行匹配
cast_abi_encode	cast abi-encode
cast_abi_decode	cast abi-decode
cast_calldata_decode	cast calldata-decode
cast_call	使用 cast call 进行只读合约交互
cast_send	使用 cast send 发送状态变更交易
cast_balance	使用 cast balance 查询 ETH 余额
cast_nonce	使用 cast nonce 查询交易 nonce
get_zksync_docs	按主题查找 foundry-zksync 文档
anvil_zksync	启动或检查本地 anvil-zksync 开发节点

先决条件

• Node.js >= 18
• 已安装 foundry-zksync（foundryup-zksync）

快速开始（npx）

无需安装——使用 npx 直接运行：

claude mcp add foundry-zksync -- npx -y foundry-zksync-mcp

或者添加到 claude_desktop_config.json / ~/.claude.json：

{
  "mcpServers": {
    "foundry-zksync": {
      "command": "npx",
      "args": ["-y", "foundry-zksync-mcp"]
    }
  }
}

从源代码安装

git clone https://github.com/Jrigada/foundry-zksync-mcp.git
cd foundry-zksync-mcp
npm install
npm run build

然后在 Claude Code 中注册：

claude mcp add foundry-zksync node /absolute/path/to/foundry-zksync-mcp/dist/index.js

密钥管理

所有签名工具（deploy、cast_send、run_script）均支持多种钱包方式。请根据安全需求选择：

本地开发（anvil-zksync）

在本地使用众所周知的测试密钥进行开发时，可直接使用 privateKey：

privateKey: "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"

这些是 anvil-zksync 的默认测试账户，不持有任何真实资产。

警告： 切勿将 privateKey 用于持有真实资金的密钥。MCP 工具参数对 AI 助手可见，也可能会被记录。

生产环境推荐：命名密钥库

密钥在磁盘上加密——只有账户名称会通过 MCP 传递。

# Import a private key into a named keystore (interactive, key never shown)
cast wallet import deployer --interactive

# List your keystores
ls ~/.foundry/keystores/

然后在任何签名工具中使用 account: "deployer"。Forge 会在运行时提示输入密码，你也可以使用 passwordFile 指定密码文件。

密钥库文件

如果你已有加密的密钥库 JSON 文件（例如来自 Geth 或 MetaMask 导出）：

keystore: "/path/to/keystore.json"
passwordFile: "/path/to/password.txt"

硬件钱包

ledger: true    # Ledger
trezor: true    # Trezor

云 KMS

aws: true       # AWS KMS (set AWS_KMS_KEY_ID env var)
gcp: true       # Google Cloud KMS (set GCP_PROJECT_ID, GCP_LOCATION, etc.)

签名方式概览

方式	密钥暴露情况	最适用场景
硬件钱包	无（密钥不会离开设备）	高价值生产环境
云 KMS	无（密钥存储在 HSM 中）	自动化生产环境
命名密钥库（account）	不会通过 MCP 暴露（在磁盘上加密）	常规生产用途
密钥库文件	不会通过 MCP 暴露（在磁盘上加密）	现有工作流
privateKey	对 AI 助手可见	仅限使用测试密钥进行本地开发

项目结构

src/
  index.ts              MCP server entry point, registers all 21 tools
  knowledge.ts          Knowledge base (45+ entries) and system addresses
  tools/
    shared.ts           Profile field and env builder shared across forge tools
    init.ts             forge init with zkSync config
    compile.ts          forge build --zksync
    test.ts             forge test --zksync
    run_script.ts       forge script --zksync
    deploy.ts           forge create --zksync (structured output)
    verify.ts           forge verify-contract --zksync
    install.ts          forge install
    clean.ts            forge clean
    gas_report.ts       forge test --gas-report
    snapshot.ts         forge snapshot
    read_foundry_toml.ts  Read project config
    explain.ts          Error/log explanation with knowledge base
    get_zksync_docs.ts  Documentation lookup with embedded content
    cast_abi_encode.ts  cast abi-encode
    cast_abi_decode.ts  cast abi-decode
    cast_calldata_decode.ts  cast calldata-decode
    cast_call.ts        cast call
    cast_send.ts        cast send
    cast_balance.ts     cast balance
    cast_nonce.ts       cast nonce
    anvil_zksync.ts     anvil-zksync node management
  __tests__/            133 tests (vitest)