eth-mcp

MCP server that enables AI agents to build and deploy Ethereum applications using Scaffold-ETH.

The AI is the planner. The MCP server is the executor.

Quick Start

Add to your Cursor MCP config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "eth-mcp": {
      "command": "npx",
      "args": ["-y", "eth-mcp@latest"]
    }
  }
}

Restart Cursor. Done! Now ask your AI:

"Build me a swapping app with a 1% tax token on Base"

What This Does

eth-mcp is a Model Context Protocol (MCP) server that:

1. Clones and configures Scaffold-ETH projects - Foundry + Next.js stack
2. Manages long-running processes - Anvil fork, contract deployment, frontend
3. Provides file access - Read/write project files
4. Exposes logs and status - Resources for agent polling
5. Includes Web3 knowledge - Guides for incentive design and Solidity patterns
6. DeFi address registry - Token and protocol addresses across 5 chains
7. DeFi yield tools - Query live APY/TVL data from DefiLlama

This enables AI agents to go from natural language to running dApp without manual intervention.

Recommended MCP Stack

eth-mcp is designed to work alongside companion MCP servers for a complete Ethereum development experience. We strongly recommend installing all three:

| MCP Server | Purpose | Essential For | |------------|---------|---------------| | eth-mcp | Build, deploy, run local dev | Core functionality | | mcp-server-ens | ENS name resolution | Resolving .eth names (vitalik.eth → 0x...) | | @blockscout/mcp-server | Blockchain exploration | Tx analysis, contract ABIs, on-chain data |

Full Configuration (Recommended)

Add all three to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "eth-mcp": {
      "command": "npx",
      "args": ["-y", "eth-mcp@latest"]
    },
    "ens": {
      "command": "npx",
      "args": ["-y", "mcp-server-ens"]
    },
    "blockscout": {
      "command": "npx",
      "args": ["-y", "@blockscout/mcp-server"]
    }
  }
}

Division of Responsibilities

| Task | eth-mcp | ENS MCP | Blockscout | |------|:-------:|:-------:|:----------:| | Scaffold project | ✅ | | | | Deploy contracts | ✅ | | | | Run local fork | ✅ | | | | Start frontend | ✅ | | | | Resolve vitalik.eth | | ✅ | | | Get ENS records (avatar, socials) | | ✅ | | | Check mainnet balances | | | ✅ | | Analyze transactions | | | ✅ | | Get contract ABIs | | | ✅ | | Look up token addresses | ✅ (registry) | | ✅ (live) | | Query live yield data | ✅ | | |

Example Workflow

1. Use ENS MCP to resolve "vitalik.eth" to get the address
2. Use Blockscout to check their USDC balance and recent transactions
3. Use eth-mcp to scaffold a project that interacts with their address
4. Use eth-mcp to write and deploy contracts locally
5. Use Blockscout to verify mainnet state your fork is based on
6. Use eth-mcp to start frontend and test

Why All Three?

• eth-mcp handles the local development loop: scaffolding, forking, deploying, hot-reloading
• ENS MCP handles name resolution: converting human-readable .eth names to addresses
• Blockscout handles blockchain exploration: reading mainnet state, analyzing transactions, fetching ABIs

The AI agent orchestrates all three, choosing the right tool for each task.

Alternative Installation (from source)

# Clone the repo
git clone https://github.com/austintgriffith/eth-mcp
cd eth-mcp

# Install dependencies
npm install

# Build
npm run build

Configure MCP Client (local)

Add to your MCP settings:

{
  "mcpServers": {
    "eth-mcp": {
      "command": "node",
      "args": ["/path/to/eth-mcp/dist/index.js"]
    }
  }
}

MCP Tools

Stack Management

| Tool | Description | |------|-------------| | stack_init | Clone Scaffold-ETH, configure for chain | | stack_install | Install dependencies (yarn install) | | stack_start | Start components: fork, deploy, frontend | | stack_stop | Stop running components | | stack_status | Get health report and URLs |

Process Management

| Tool | Description | |------|-------------| | process_list | List all managed processes | | process_logs | Get stdout/stderr for a process | | process_stop | Stop a specific process |

Project Files

| Tool | Description | |------|-------------| | project_readFile | Read a project file | | project_writeFile | Write content to a file | | project_listFiles | List directory contents |

MCP Resources

Resources for polling status and logs:

| Resource URI | Description | |--------------|-------------| | resource://stack/status | Current stack health | | resource://stack/config | Stack configuration | | resource://process/fork/stdout | Anvil fork output | | resource://process/fork/stderr | Anvil fork errors | | resource://process/frontend/stdout | Next.js output | | resource://process/frontend/stderr | Next.js errors | | resource://contracts/deployed | Deployed contract addresses |

Example Agent Workflow

Here's how an AI agent would build a tax token swap app:

Agent: "Build a swapping app with a 1% tax token on Base"

1. stack_init({ template: "scaffold-eth", chain: "base", workspacePath: "/tmp/tax-swap" })
   → Clones scaffold-eth-2, configures for Base

2. stack_install()
   → Runs yarn install

3. project_writeFile({ path: "packages/foundry/contracts/TaxToken.sol", content: "..." })
   → Creates the tax token contract

4. project_writeFile({ path: "packages/foundry/script/Deploy.s.sol", content: "..." })
   → Updates deploy script

5. stack_start({ components: ["fork", "deploy", "frontend"] })
   → Starts Anvil fork of Base
   → Deploys contracts
   → Starts Next.js

6. stack_status()
   → Returns: { urls: { rpc: "http://localhost:8545", frontend: "http://localhost:3000" } }

7. project_writeFile({ path: "packages/nextjs/app/page.tsx", content: "..." })
   → Creates swap UI on home page

Result: Running app at http://localhost:3000

Supported Chains

| Chain | ID | Fork RPC | |-------|----|-| | mainnet | 1 | Public RPC | | base | 8453 | Public RPC | | optimism | 10 | Public RPC | | arbitrum | 42161 | Public RPC | | polygon | 137 | Public RPC | | sepolia | 11155111 | Public RPC |

Documentation for AI Agents

The docs/ folder contains guides that help AI agents understand Web3 development:

• WEB3_DEVELOPMENT_GUIDE.md - Mental model shift, incentive thinking, security patterns
• SOLIDITY_PATTERNS.md - Common contract patterns and templates
• DEFI_BUILDING_BLOCKS.md - DeFi primitives and composability

AI agents should read these before building complex applications.

Protocol Packs

Example protocol integrations in protocol-packs/:

uniswap-v4-tax-swap

Placeholder implementation of:

• TaxToken.sol - ERC-20 with 1% transfer tax
• TaxSwapHook.sol - Uniswap V4 hook for tax handling
• SwapUI.tsx - React swap interface

This shows structure, not full implementation. V4 is still in development.

Safety

The server enforces several safety constraints:

Command Allowlist:

• Only git, yarn, npm, pnpm, npx, forge, anvil, cast, node

Private Key Protection:

• Sanitizes output to remove private keys
• Blocks access to .env files
• Filters sensitive environment variables

No Mainnet Writes:

• Local development only
• Fork-based testing

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      AI Agent                               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  "Build me a swapping app with a 1% tax token"      │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────┬───────────────────────────────────┘
                          │ MCP Protocol
┌─────────────────────────▼───────────────────────────────────┐
│                       eth-mcp                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Stack   │  │ Process  │  │ Project  │  │Resources │   │
│  │  Tools   │  │ Manager  │  │  Tools   │  │          │   │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
└───────┼─────────────┼─────────────┼─────────────┼──────────┘
        │             │             │             │
┌───────▼─────────────▼─────────────▼─────────────▼──────────┐
│                     Workspace                               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │               scaffold-eth-2                         │   │
│  │  ┌───────────────┐  ┌───────────────────────────┐   │   │
│  │  │   Foundry     │  │        Next.js            │   │   │
│  │  │  (Contracts)  │  │       (Frontend)          │   │   │
│  │  └───────────────┘  └───────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────┐  ┌─────────────────────────────────┐  │
│  │  Anvil Fork     │  │     http://localhost:3000       │  │
│  │  (Base chain)   │  │         (Running app)           │  │
│  └─────────────────┘  └─────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Development

# Watch mode
npm run dev

# Type check
npm run typecheck

# Run server directly
npm start

Limitations (v1)

• Local development only (no mainnet deployment)
• Single workspace at a time
• Basic error recovery
• Placeholder protocol pack implementations

License

MIT