Skip to content
Back to search

foundry-mcp-server

An experimental MCP Server for foundry built for Solidity devs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/praneshasp--foundry-mcp-server/badge.svg)](/listings/praneshasp--foundry-mcp-server)

HTML

<a href="/listings/praneshasp--foundry-mcp-server"><img src="/api/listings/praneshasp--foundry-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

1. Ensure Foundry tools (Forge, Cast, Anvil) are installed on your system:

   curl -L https://foundry.paradigm.xyz | bash
   foundryup

2. Clone and build the server.

```sh bun i && bun build ./src/index.ts --outdir ./dist --target node

3. Update your client config (eg: Claude desktop):

 "mcpServers": {
    "foundry": {
      "command": "node",
      "args": [
        "path/to/foundry-mcp-server/dist/index.js"
      ],
      "env" :{
        "PRIVATE_KEY": "0x1234",
      }
    }
 }

> [!NOTE] > `PRIVATE_KEY` is optional

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 248 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Foundry MCP Server
  2. A simple, lightweight and fast MCP (Model Context Protocol) server that provides Solidity development capabilities using the Foundry toolchain (Forge, Cast, and Anvil).
  3. ![Foundry MCP Demo](./assets/analysis_gif.gif)
  4. ## Overview
  5. This server connects LLM assistants to the Foundry ecosystem, enabling them to:
  6. - Interact with nodes (local Anvil instances or remote RPC endpoints)
  7. - Analyze smart contracts and blockchain data
  8. - Perform common EVM operations using Cast
  9. - Manage, deploy, and execute Solidity code and scripts
  10. - Work with a persistent Forge workspace
  11. ## Features
  12. ### Network Interaction
  13. - Start and manage local Anvil instances
  14. - Connect to any remote network (just specify the RPC)
  15. - Get network/chain information
  16. ### Contract Interaction
  17. - Call contract functions (read-only)
  18. - Send transactions to contracts (if `PRIVATE_KEY` is configured)
  19. - Get transaction receipts
  20. - Read contract storage
  21. - Analyze transaction traces
  22. - Retrieve contract ABIs and sources from block explorers
  23. ### Solidity Development
  24. - Maintain a dedicated Forge workspace
  25. - Create and edit Solidity files
  26. - Install dependencies
  27. - Run Forge scripts
  28. - Deploy contracts
  29. ### Utility Functions
  30. - Calculate contract addresses
  31. - Check contract bytecode size
  32. - Estimate gas costs
  33. - Convert between units (hex to decimals, etc.,)
  34. - Generate wallets
  35. - Get event logs
  36. - Lookup function and event signatures
  37. ### Smart Contract Analysis (Heimdall)
  38. - Disassemble EVM bytecode into human-readable opcodes
  39. - Decode raw calldata without requiring ABI
  40. - Decompile EVM bytecode to Solidity source code and ABI
  41. - Generate visual control flow graphs for EVM bytecode
  42. - Detailed transaction inspection with calldata decoding and trace analysis
  43. ## Usage
  44. The server is designed to be used as an MCP tool provider for MCP Clients. When connected to a client, it enables the clients(claude desktop, cursor, client, etc.,) to perform Solidity and onchain operations directly.
  45. #### Requirements
  46. - [Node.js v18+](https://nodejs.org)
  47. - [Foundry toolchain](https://book.getfoundry.sh/) (Forge, Cast, Anvil)
  48. - [Heimdall-rs](https://github.com/Jon-Becker/heimdall-rs) (for smart contract analysis)
  49. ### Manual Setup
  50. 1. Ensure Foundry tools (Forge, Cast, Anvil) are installed on your system:
  51. ```
  52. curl -L https://foundry.paradigm.xyz | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 75 on GitHub
  53. foundryup
  54. ```
  55. 2. Clone and build the server.
  56. ```sh
  57. bun i && bun build ./src/index.ts --outdir ./dist --target node
  58. 3. Update your client config (eg: Claude desktop):
  59. ```json
  60. "mcpServers": {
  61. "foundry": {
  62. "command": "node",
  63. "args": [
  64. "path/to/foundry-mcp-server/dist/index.js"
  65. ],
  66. "env" :{
  67. "PRIVATE_KEY": "0x1234",
  68. }
  69. }
  70. }
  71. ```
  72. > [!NOTE]
  73. > `PRIVATE_KEY` is optional
  74. ### Setup using NPM Package
  75. You can now install and run the server directly using npm:
  76. #### Global Installation
  77. ```bash
  78. npm install -g @pranesh.asp/foundry-mcp-server
  79. ```
  80. #### Direct Usage with npx
  81. ```bash
  82. npx @pranesh.asp/foundry-mcp-server
  83. ```
  84. #### MCP Client Configuration
  85. **Claude Code**
  86. ```bash
  87. claude mcp add-json foundry-mcp-server '{"type":"stdio","command":"npx","args":["@pranesh.asp/foundry-mcp-server"],"env":{"RPC_URL":"","PRIVATE_KEY":""}}'
  88. ```
  89. **Other MCP Clients (Cursor, Claude, Windsurf)**
  90. Add to your MCP settings:
  91. ```json
  92. {
  93. "mcpServers": {
  94. "foundry": {
  95. "command": "npx",
  96. "args": ["@pranesh.asp/foundry-mcp-server"],
  97. "env": {
  98. "RPC_URL": "http://localhost:8545",
  99. "PRIVATE_KEY": "0x..."
  100. }
  101. }
  102. }
  103. }
  104. ```
  105. #### Configuration
  106. The server supports the following environment variables:
  107. - `RPC_URL`: Default RPC URL to use when none is specified (optional)
  108. - `PRIVATE_KEY`: Private key to use for transactions (optional)
  109. > [!CAUTION]
  110. > Do not add keys with mainnet funds. Even though the code uses it safely, LLMs can hallicunate and send malicious transactions.
  111. > Use it only for testing/development purposes. DO NOT trust the LLM!!
  112. > [!TIP]
  113. > Getting `Invalid configuration` errors? Check your JSON syntax—common issues include double quotes (`""KEY"` → `"KEY"`), trailing commas, or unquoted keys. Validate with `echo '...' | jq .`
  114. ### Workspace
  115. The server maintains a persistent Forge workspace at `~/.mcp-foundry-workspace` for all Solidity files, scripts, and dependencies.
  116. ## Tools
  117. ### Anvil
  118. - `anvil_start`: Start a new Anvil instance
  119. - `anvil_stop`: Stop a running Anvil instance
  120. - `anvil_status`: Check if Anvil is running and get its status
  121. ### Cast
  122. - `cast_call`: Call a contract function (read-only)
  123. - `cast_send`: Send a transaction to a contract function
  124. - `cast_balance`: Check the ETH balance of an address
  125. - `cast_receipt`: Get the transaction receipt
  126. - `cast_storage`: Read contract storage at a specific slot
  127. - `cast_run`: Run a published transaction in a local environment
  128. - `cast_logs`: Get logs by signature or topic
  129. - `cast_sig`: Get the selector for a function or event signature
  130. - `cast_4byte`: Lookup function or event signature from the 4byte directory
  131. - `cast_chain`: Get information about the current chain
  132. ### Forge
  133. - `forge_script`: Run a Forge script from the workspace
  134. - `install_dependency`: Install a dependency for the Forge workspace
  135. ### File Management
  136. - `create_solidity_file`: Create or update a Solidity file in the workspace
  137. - `read_file`: Read the content of a file from the workspace
  138. - `list_files`: List files in the workspace
  139. ### Utilities
  140. - `convert_eth_units`: Convert between EVM units (wei, gwei, hex)
  141. - `compute_address`: Compute the address of a contract that would be deployed
  142. - `contract_size`: Get the bytecode size of a deployed contract
  143. - `estimate_gas`: Estimate the gas cost of a transaction
  144. ### Heimdall Analysis
  145. - `heimdall_disassemble`: Disassemble EVM bytecode into human-readable opcodes
  146. - `heimdall_decode`: Decode raw calldata without requiring ABI
  147. - `heimdall_decompile`: Decompile EVM bytecode to Solidity source code and ABI
  148. - `heimdall_cfg`: Generate visual control flow graph for EVM bytecode
  149. - `heimdall_inspect`: Detailed inspection of Ethereum transactions
  150. ## Usage in Claude Desktop App 🎯
  151. Once the installation is complete, and the Claude desktop app is configured, you must completely close and re-open the Claude desktop app to see the tavily-mcp server. You should see a hammer icon in the bottom left of the app, indicating available MCP tools, you can click on the hammer icon to see more details on the available tools.
  152. ![Alt text](./assets/tools.png)
  153. Now claude will have complete access to the foundry-mcp server. If you insert the below examples into the Claude desktop app, you should see the foundry-mcp server tools in action.
  154. ### Examples
  155. 1. **Transaction analysis**:
  156. ```
  157. Can you analyze the transaction and explain what it does?
  158. https://etherscan.io/tx/0xcb73ad3116f19358e2e649d4dc801b7ae0590a47b8bb2e57a8e98b6daa5fb14b
  159. ```
  160. 2. **Querying Balances**:
  161. ```
  162. Query the mainnet ETH and USDT balances for the wallet 0x195F46025a6926968a1b3275822096eB12D97E70.
  163. ```
  164. 3. **Sending transactions**:
  165. ```
  166. Transfer 0.5 USDC to 0x195F46025a6926968a1b3275822096eB12D97E70 on Mainnet.
  167. ```
  168. 4. **Deploying contracts/Running scripts**:
  169. ```
  170. Deploy a mock ERC20 contract to a local anvil instance and name it "Fire Coin".
  171. ```
  172. ## Acknowledgments ✨
  173. - [Model Context Protocol](https://modelcontextprotocol.io) for the MCP specification
  174. - [Anthropic](https://anthropic.com) for Claude Desktop
  175. ## Disclaimer
  176. _The software is being provided as is. No guarantee, representation or warranty is being made, express or implied, as to the safety or correctness of the software. They have not been audited and as such there can be no assurance they will work as intended, and users may experience delays, failures, errors, omissions, loss of transmitted information or loss of funds. The creators are not liable for any of the foregoing. Users should proceed with caution and use at their own risk._

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.