Anvil

You use MCP Anvil Tools to interact with Solidity contracts and simulate Ethereum transactions locally. Built on a local Anvil node, it lets you read source and storage, run transactions in isolated environments, manipulate state with snapshots and impersonation, and trace and decode activity. This enables AI-powered auditing, testing workflows, and automated blockchain development tasks with confidence.

How to use

You connect your MCP client to the server over HTTP or run it locally via stdio. Use the HTTP mode when you want web-based or multi-agent integrations, and use the stdio mode for desktop tooling and CLI scripts. You can perform read operations to inspect contracts, simulate transactions to validate logic, actually send transactions on a test network, impersonate accounts to test scenarios, and manage Anvil state through snapshots and reverts. Tracing tools help you debug complex interactions and inspect call paths.

Typical usage patterns include: reading a contract’s source and bytecode, inspecting contract storage, simulating a transaction to see the expected return data, then sending the transaction if the simulation looks correct. You can create a snapshot before running a potentially state-changing sequence, perform the actions you want, and revert back to the snapshot if needed. For auditing, you can trace transactions or specific calls to understand how contracts behave under different inputs.

How to install

Prerequisites: you need Node.js and npm installed on your system. You also require a working environment for running Anvil (Foundry) if you plan to use the Anvil integration features.

Clone the project, install dependencies, and build the project to prepare the MCP server for use.

# Clone the repository
git clone https://github.com/yourusername/mcp-anvil-tools.git
cd mcp-anvil-tools

# Install dependencies
npm install

# Build the project
npm run build

Configuration and operation

Configure environment variables to set up porting, RPC endpoints, and API keys. You define the port for the HTTP server, the RPC URL for mainnet interactions, and an optional API key for source verification.

Start the server in HTTP mode for web clients or multi-agent systems.

Start the server in stdio mode for Claude Desktop or CLI tooling.

For development, you can run in watch mode to enable hot reloads during active development.

Security and best practices

Impersonation is limited to the Anvil environment and not usable on production networks. Never log or expose private keys. Use secure RPC endpoints with authentication. Validate state overrides carefully to prevent unintended effects. Set reasonable gas limits to avoid accidental DoS conditions. Validate all inputs using rigid schemas to prevent malformed requests.

Troubleshooting

If the server won’t start, check that the port you want is free and your environment variables are correctly configured. If Anvil connections fail, ensure Anvil is installed and the port range is correctly configured. For tool execution errors, verify the RPC endpoint is reachable and the target contract exists. In stdio mode, ensure one JSON-RPC message per line and monitor stderr for log messages.

Notes on workflows and examples

Common workflows include reading sources and bytecode, inspecting storage slots, simulating a transaction before sending it, and taking a snapshot before running potentially state-changing operations. If needed, revert to a previous snapshot to restore the state.

Development and testing rely on a combination of HTTP and stdio transport modes, with the HTTP endpoint enabling web-based clients and the stdio mode enabling local tooling and scripted automation.

Available tools

read_source

Read Solidity source code files from the v4-core repository, returning content, line count, absolute path, size, and last modified time.

read_storage

Read contract storage slots (persistent storage only) and return raw values with optional decoded interpretation.

read_bytecode

Retrieve deployed bytecode for a contract address, including size and code hash.

read_events

Query and decode contract event logs with optional filtering by event signature and topics.

simulate_tx

Simulate a transaction locally to inspect return data and possible reverts without sending it to the network.

send_tx

Send actual transactions to the network and return transaction receipt details including status and logs.

impersonate

Impersonate any address on Anvil for testing purposes (non-production use only).

create_snapshot

Create an Anvil state snapshot to enable quick reversion to a known state.

revert_snapshot

Revert the blockchain state to a previously created snapshot.

trace_transaction

Trace an existing transaction with a selected tracer to inspect execution details.

trace_call

Trace a contract call at a given block without sending a transaction to inspect behavior.