home / mcp / foundry mcp server

Foundry MCP Server

Provides Solidity development with Foundry tools, on-chain analysis, and workspace management for Forge, Cast, and Anvil.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "praneshasp-foundry-mcp-server": {
      "command": "npx",
      "args": [
        "@pranesh.asp/foundry-mcp-server"
      ]
    }
  }
}

You can run a lightweight MCP server that integrates the Foundry toolchain to enable Solidity development, contract analysis, and on-chain interactions from your MCP clients. This server connects to Anvil or remote RPC endpoints, lets you manage a Forge workspace, and provides Cast, Forge, and Heimdall-powered capabilities for building, deploying, and inspecting Solidity code and transactions.

How to use

You connect an MCP client to the Foundry MCP Server to perform Solidity development and on-chain operations. After connection, you can start local Anvil instances, connect to remote networks via RPC URLs, call read-only contract functions, send transactions when you provide a private key, read storage, analyze traces, and work with a persistent Forge workspace. You will also have access to tools for bytecode disassembly, calldata decoding, and decompilation to Solidity.

How to install

Prepare your environment with the required tools and then install and run the server using the recommended workflows.

# Prerequisites
# Node.js v18+ and Foundry toolchain (Forge, Cast, Anvil)
# Heimdall-rs for smart contract analysis

# Foundry installation (Manual setup steps)
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Manual build flow (from the source repository)
bun i && bun build ./src/index.ts --outdir ./dist --target node

# Direct usage with npm/npx (example after building is available via npm package)
npx @pranesh.asp/foundry-mcp-server

Client configuration and startup

Configure your MCP client to load the server. Use the following example to connect via a standard MCP client configuration. You can supply a private key for transaction-sending capabilities if needed.

{
  "mcpServers": {
    "foundry": {
      "command": "npx",
      "args": ["@pranesh.asp/foundry-mcp-server"],
      "env": {
        "RPC_URL": "",
        "PRIVATE_KEY": ""
      }
    }
  }
}

Manual start flow (build then run)

The server is built and run through a direct npm/npx workflow. Build the server locally, then run it with an MCP client configuration that points to the installed package.

# Build and prepare the workspace
bun i && bun build ./src/index.ts --outdir ./dist --target node

# Start using the MCP client flow (example via npx)
npx @pranesh.asp/foundry-mcp-server

Security and best practices

Do not expose private keys or funds to the MCP server. The PRIVATE_KEY field is optional and should be used only for testing or development. Treat all private keys with care and avoid triggering real mainnet transactions from the MCP client.

Workspace and file management

Your Forge workspace is persistent at the following location to keep Solidity files, scripts, and dependencies organized across sessions.

~/.mcp-foundry-workspace

Using the Foundry MCP Server with Claude Desktop or other MCP clients

Once you configure the MCP client and restart the client application, you will see the Foundry MCP tools available. You can use the provided examples to analyze transactions, query balances, send transactions, and deploy or run scripts against a local Anvil instance or a remote RPC.

Examples of common tasks

- Analyze a transaction to understand its behavior on-chain.

- Query balances for ETH and ERC20 tokens.

- Deploy a mock ERC20 contract to a local Anvil instance and interact with it.

Available tools

anvil_start

Start a new local Anvil instance to provide a private blockchain network for testing and development.

anvil_stop

Stop the currently running Anvil instance.

anvil_status

Check if Anvil is running and retrieve its status.

cast_call

Call a contract function in read-only mode using the Cast tool.

cast_send

Send a transaction to a contract function using the Cast tool.

cast_balance

Check the ETH balance of an address using the Cast tool.

cast_receipt

Retrieve the transaction receipt for a given transaction hash.

cast_storage

Read storage at a specific slot for a contract address.

cast_run

Run a published transaction in a local environment.

cast_logs

Fetch logs by signature or topic using the Cast tool.

cast_sig

Get the function or event selector for a signature.

cast_4byte

Lookup function or event signature from the 4byte directory.

cast_chain

Get information about the current blockchain network.

forge_script

Run a Forge script from the persistent workspace.

install_dependency

Install a dependency for the Forge workspace.

create_solidity_file

Create or update a Solidity file in the Forge workspace.

read_file

Read the content of a file from the Forge workspace.

list_files

List files in the Forge workspace.

convert_eth_units

Convert between ETH units (wei, gwei, ether) and related representations.

compute_address

Compute the address of a contract before deployment.

contract_size

Get the bytecode size of a deployed contract.

estimate_gas

Estimate the gas cost of a transaction.

heimdall_disassemble

Disassemble EVM bytecode into human-readable opcodes.

heimdall_decode

Decode raw calldata without requiring an ABI.

heimdall_decompile

Decompile EVM bytecode to Solidity source code and ABI.

heimdall_cfg

Generate a visual control flow graph for EVM bytecode.

heimdall_inspect

Detailed inspection of Ethereum transactions.