foundry-zksync-mcp

An MCP (Model Context Protocol) server that exposes foundry-zksync CLI tools to AI assistants like Claude.

Tools

Tool	Description
`init`	`forge init` with automatic zkSync config
`compile`	`forge build --zksync`
`test`	`forge test --zksync` with filter/verbosity options
`run_script`	`forge script --zksync` with broadcast, sender, slow mode
`deploy`	`forge create --zksync` with structured output parsing
`verify`	`forge verify-contract --zksync` (Etherscan & zkSync Explorer)
`install`	`forge install` for dependency management
`clean`	`forge clean` to remove build artifacts
`gas_report`	`forge test --gas-report` for gas usage analysis
`snapshot`	`forge snapshot` for gas benchmarking
`read_foundry_toml`	Read and inspect project configuration
`explain`	Match errors/logs against a knowledge base of zkSync gotchas
`cast_abi_encode`	`cast abi-encode`
`cast_abi_decode`	`cast abi-decode`
`cast_calldata_decode`	`cast calldata-decode`
`cast_call`	`cast call` for read-only contract interaction
`cast_send`	`cast send` for state-changing transactions
`cast_balance`	`cast balance` for ETH balance queries
`cast_nonce`	`cast nonce` for transaction nonce queries
`get_zksync_docs`	Look up foundry-zksync documentation by topic
`anvil_zksync`	Start or check a local anvil-zksync dev node

Prerequisites

Node.js >= 18
foundry-zksync installed (foundryup-zksync)

Quick Start (npx)

No install needed — run directly with npx:

Terminal

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

Or add to claude_desktop_config.json / ~/.claude.json:

config.json

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

Install from Source

bash

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

Then register with Claude Code:

Terminal

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

Key Management

All signing tools (deploy, cast_send, run_script) support multiple wallet methods. Choose based on your security needs:

Local Development (anvil-zksync)

For local dev with well-known test keys, use privateKey directly:

Code

privateKey: "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"

These are the default anvil-zksync test accounts — they hold no real value.

Warning: Never use privateKey with keys that hold real funds. MCP tool parameters are visible to the AI assistant and may be logged.

Recommended for Production: Named Keystores

Keys are encrypted on disk — only the account name travels through MCP.

server.ts

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

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

Then use account: "deployer" in any signing tool. Forge will prompt for the password at runtime, or you can point to a password file with passwordFile.

Keystore Files

If you have an existing encrypted keystore JSON file (e.g. from Geth, MetaMask export):

Code

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

Hardware Wallets

Code

ledger: true    # Ledger
trezor: true    # Trezor

Cloud KMS

Code

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

Signing Method Summary

Method	Key Exposure	Best For
Hardware wallet	None (key never leaves device)	High-value production
Cloud KMS	None (key in HSM)	Automated production
Named keystore (`account`)	None through MCP (encrypted on disk)	General production use
Keystore file	None through MCP (encrypted on disk)	Existing workflows
`privateKey`	Visible to AI assistant	Local dev with test keys only

Project Structure

Code

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)