MCP Server

Active

MIT

EVMole MCP Server

io.github.cdump/evmole

Extract function selectors, arguments, and state mutability from EVM bytecode without verification.

What is the EVMole MCP server?

EVMole is a library that extracts structured information from Ethereum Virtual Machine (EVM) bytecode, including function selectors, arguments, state mutability, storage layouts, and CBOR metadata. It works on both verified and unverified contracts across Solidity and Vyper, with high accuracy and performance.

EVMole analyzes deployed EVM runtime bytecode to reverse-engineer contract interfaces and metadata. It identifies function selectors, parameter types, state mutability (view/pure/payable), and storage layouts without requiring source code or contract verification. This is useful for security analysis, contract interaction, and understanding unverified smart contracts on-chain.

How to install EVMole

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

~/Library/Application Support/Claude/claude_desktop_config.json

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

Tools & capabilities

Tools this server exposes to the agent.

analyze — Extract function selectors, arguments, state mutability, storage layouts, and CBOR metadata from EVM bytecode
contract_info — Retrieve structured contract information including function dispatch classification, bytecode offsets, and argument types

Use cases

Analyze unverified smart contracts to discover their function interfaces and signatures
Extract function selectors and argument types from deployed bytecode for interaction without ABI
Determine state mutability (view/pure/payable/nonpayable) of contract functions from bytecode alone
Reverse-engineer storage layouts and CBOR metadata from compiled EVM contracts
Distinguish between normal ABI dispatch and fallback function handlers in bytecode

EVMole MCP server FAQ

What is EVMole?

EVMole is a bytecode analysis library that extracts function selectors, arguments, state mutability, and metadata from EVM bytecode without requiring source code or contract verification.

Does EVMole require contract verification?

No. EVMole works on unverified contracts by analyzing the deployed bytecode directly, making it useful for analyzing any contract on-chain.

How do I use EVMole as an MCP server?

Install with `npm install -g evmole-mcp` or run `npx -y evmole-mcp` to start the local MCP server, which exposes EVMole as typed tools for Claude and other AI agents.

What languages does EVMole support?

EVMole is available as JavaScript, Rust, Python, and Go libraries. The MCP server is the Node.js/JavaScript integration.

Is EVMole free to use?

Yes, EVMole is open-source and free. It runs locally without sending bytecode to external services.

What bytecode does EVMole analyze?

EVMole analyzes deployed/runtime EVM bytecode from Solidity and Vyper contracts. It extracts function selectors, argument types, state mutability, storage layouts, and CBOR metadata.

README (reference)

Source of truth, from the repository.

EVMole is a powerful library that extracts information from Ethereum Virtual Machine (EVM) bytecode, including function selectors, arguments, state mutability, persistent and transient storage layouts, and CBOR metadata, even for unverified contracts.

Key Features

Multi-language support: Available as JavaScript, Rust, Python, and Go libraries.
High accuracy and performance: Outperforms existing tools.
Broad compatibility: Tested with both Solidity and Vyper compiled contracts.
Lightweight: Clean codebase with minimal external dependencies.
Unverified contract analysis: Extracts information even from unverified bytecode.
Selector dispatch classification: Distinguishes normal ABI dispatch from selectors handled by fallback logic.
CBOR metadata: Extracts string-keyed values from a terminal, length-suffixed CBOR map without assuming a particular compiler.

Usage

JavaScript

API documentation and usage examples (Node.js, Vite, webpack, Parcel, esbuild)

npm i evmole

import { contractInfo } from 'evmole'

const code = '0x6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256'

console.log( contractInfo(code, {selectors:true, arguments:true, stateMutability:true}) )
// {
//   functions: [
//     {
//       selector: '2125b65b',
//       bytecodeOffset: 52,
//       dispatch: 'abi',
//       arguments: 'uint32,address,uint224',
//       stateMutability: 'pure'
//     },
//     ...

Rust

Documentation is available on docs.rs

let code = hex::decode("6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256").unwrap();

println!("{:?}", evmole::contract_info(
    evmole::ContractInfoArgs::new(&code)
        .with_selectors()
        .with_arguments()
        .with_state_mutability()
    )
);
// Contract {
//     functions: Some([
//         Function {
//             selector: [33, 37, 182, 91],
//             bytecode_offset: 52,
//             dispatch: Abi,
//             arguments: Some([Uint(32), Address, Uint(224)]),
//             state_mutability: Some(Pure)
//         },
//         ...

Python

API documentation

pip install evmole --upgrade

from evmole import contract_info

code = '0x6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256'

print( contract_info(code, selectors=True, arguments=True, state_mutability=True) )
# Contract(
#     functions=[
#     Function(
#             selector=2125b65b,
#             bytecode_offset=52,
#             dispatch="abi",
#             arguments=uint32,address,uint224,
#             state_mutability=pure),
#     ...

Go

API documentation

go get github.com/cdump/evmole/go

package main

import (
    "context"
    "encoding/hex"
    "fmt"

    "github.com/cdump/evmole/go"
)

func main() {
    code, _ := hex.DecodeString("6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256")

    info, _ := evmole.ContractInfo(context.Background(), code, evmole.Options{
        Selectors:       true,
        Arguments:       true,
        StateMutability: true,
    })

    for _, fn := range info.Functions {
        fmt.Printf("%s: %s @ %d\n", fn.Selector, *fn.Arguments, fn.BytecodeOffset)
    }
    // 2125b65b: uint32,address,uint224 @ 52
    // b69ef8a8:  @ 68
}

Foundry

<a href="https://getfoundry.sh/">Foundry's cast</a> uses the Rust implementation of EVMole


$ cast selectors $(cast code 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)
0x06fdde03                           view
0x095ea7b3  address,uint256          nonpayable
0x18160ddd                           view
0x23b872dd  address,address,uint256  nonpayable
...

$ cast selectors --resolve $(cast code 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)
0x06fdde03                           view        name()
0x095ea7b3  address,uint256          nonpayable  approve(address,uint256)
0x18160ddd                           view        totalSupply()
0x23b872dd  address,address,uint256  nonpayable  transferFrom(address,address,uint256)
...

AI agents

For application code, use one of the language bindings above. For agent-driven bytecode analysis, choose one integration.

JSON CLI

Use for one-off analysis and scripts:

npx -y evmole analyze --bytecode 0x...

Portable skill

Install routing and interpretation guidance for supported agents:

npx skills add cdump/evmole --skill evm-bytecode-analysis -g

Local MCP server

Expose EVMole as a typed local tool:

npx -y evmole-mcp

All integrations expect deployed/runtime bytecode and run locally without sending bytecode to an EVMole-operated service. See the agent integration guide for setup, schemas, limitations, and privacy details.

Benchmark

function selectors

FP/FN - False Positive/False Negative errors; smaller is better

<table> <tr> <td>Dataset</td> <td></td> <td>evmole <a href="benchmark/providers/evmole-rs/">rs</a> · <a href="benchmark/providers/evmole-js/">js</a> · <a href="benchmark/providers/evmole-py/">py</a> · <a href="benchmark/providers/evmole-go/">go</a></td> <td><a href="benchmark/providers/whatsabi/">whatsabi</a></td> <td><a href="benchmark/providers/sevm/">sevm</a></td> <td><a href="benchmark/providers/evm-hound-rs/">evmhound</a></td> <td><a href="benchmark/providers/heimdall-rs/">heimdall</a></td> </tr> <tr> <td rowspan="5">coverage2k solidity 2000 addresses 45650 functions</td> <td>FP addrs</td> <td>0 🥇</td> <td>4</td> <td>1</td> <td>56</td> <td>3</td> </tr> <tr> <td>FN addrs</td> <td>0 🥇</td> <td>11</td> <td>0 🥇</td> <td>224</td> <td>166</td> </tr> <tr> <td>FP funcs</td> <td>0 🥇</td> <td>10</td> <td>10</td> <td>616</td> <td>27</td> </tr> <tr> <td>FN funcs</td> <td>0 🥇</td> <td>145</td> <td>0 🥇</td> <td>821</td> <td>342</td> </tr> <tr> <td>Time</td> <td>24ms · 0.3s · 31ms · 0.1s</td> <td>2.0s</td> <td>28s(*)</td> <td>86ms</td> <td>111s(*)</td> </tr> <tr><td colspan="7"></td></tr> <tr> <td rowspan="5">random10k solidity 10000 addresses 223316 functions</td> <td>FP addrs</td> <td>0 🥇</td> <td>19</td> <td>16</td> <td>224</td> <td>7</td> </tr> <tr> <td>FN addrs</td> <td>0 🥇</td> <td>44</td> <td>1</td> <td>838</td> <td>819</td> </tr> <tr> <td>FP funcs</td> <td>0 🥇</td> <td>65</td> <td>112</td> <td>3157</td> <td>260</td> </tr> <tr> <td>FN funcs</td> <td>0 🥇</td> <td>173</td> <td>7</td> <td>4112</td> <td>1021</td> </tr> <tr> <td>Time</td> <td>0.1s · 0.8s · 0.2s · 0.8s</td> <td>7.1s</td> <td>80s(*)</td> <td>0.4s</td> <td>533s(*)</td> </tr> <tr><td colspan="7"></td></tr> <tr> <td rowspan="5">coverage1k vyper 1000 addresses 38759 functions</td> <td>FP addrs</td> <td>0 🥇</td> <td>560</td> <td>0 🥇</td> <td>2</td> <td>0 🥇</td> </tr> <tr> <td>FN addrs</td> <td>0 🥇</td> <td>998</td> <td>788</td> <td>525</td> <td>998</td> </tr> <tr> <td>FP funcs</td> <td>0 🥇</td> <td>560</td> <td>0 🥇</td> <td>5</td> <td>0 🥇</td> </tr> <tr> <td>FN funcs</td> <td>0 🥇</td> <td>38759</td> <td>34077</td> <td>16218</td> <td>38759</td> </tr> <tr> <td>Time</td> <td>91ms · 0.4s · 0.1s · 0.3s</td> <td>1.9s</td> <td>5.4s(*)</td> <td>67ms</td> <td>12s(*)</td> </tr> </table>

function arguments

Errors - when at least 1 inferred argument is incorrect: (uint256,string) ≠ (uint256,bytes)

<table> <tr> <td>Dataset</td> <td></td> <td>evmole <a href="benchmark/providers/evmole-rs/">rs</a> · <a href="benchmark/providers/evmole-js/">js</a> · <a href="benchmark/providers/evmole-py/">py</a> · <a href="benchmark/providers/evmole-go/">go</a></td> <td><a href="benchmark/providers/heimdall-rs/">heimdall</a></td> </tr> <tr> <td rowspan="2">coverage2k solidity 45650 functions</td> <td>Errors</td> <td>8.5% 🥇 3883</td> <td>23.3% 10643</td> </tr> <tr> <td>Time</td> <td>0.8s · 1.7s · 1.1s · 2.1s</td> <td>111s(*)</td> </tr> <tr><td colspan="4"></td></tr> <tr> <td rowspan="2">random10k solidity 223316 functions</td> <td>Errors</td> <td>6.8% 🥇 15296</td> <td>21.4% 47878</td> </tr> <tr> <td>Time</td> <td>3.5s · 6.9s · 4.2s · 9.7s</td> <td>511s(*)</td> </tr> <tr><td colspan="4"></td></tr> <tr> <td rowspan="2">coverage1k vyper 38759 functions</td> <td>Errors</td> <td>45.4% 🥇 17590</td> <td>100.0% 38759</td> </tr> <tr> <td>Time</td> <td>0.5s · 1.1s · 0.6s · 1.4s</td> <td>12s(*)</td> </tr> </table>

function state mutability

Errors - Results are not equal (treating view and pure as equivalent to nonpayable)

Errors strict - Results are strictly unequal (nonpayable ≠ view). Some ABIs mark pure/view functions as nonpayable, so not all strict errors indicate real issues.

<table> <tr> <td>Dataset</td> <td></td> <td>evmole <a href="benchmark/providers/evmole-rs/">rs</a> · <a href="benchmark/providers/evmole-js/">js</a> · <a href="benchmark/providers/evmole-py/">py</a> · <a href="benchmark/providers/evmole-go/">go</a></td> <td><a href="benchmark/providers/whatsabi/">whatsabi</a></td> <td><a href="benchmark/providers/sevm/">sevm</a></td> <td><a href="benchmark/providers/heimdall-rs/">heimdall</a></td> </tr> <tr> <td rowspan="3">coverage2k solidity 45647 functions</td> <td>Errors</td> <td>0.0% 🥇 18</td> <td>52.2% 23810</td> <td>11.2% 5133</td> <td>19.6% 8951</td> </tr> <tr> <td>Errors strict</td> <td>9.0% 🥇 4107</td> <td>70.9% 32346</td> <td>62.3% 28429</td> <td>41.3% 18835</td> </tr> <tr> <td>Time</td> <td>10s · 11s · 9.7s · 20s</td> <td>3.1s</td> <td>29s(*)</td> <td>112s(*)</td> </tr> <tr><td colspan="6"></td></tr> <tr> <td rowspan="3">random10k solidity 223273 functions</td> <td>Errors</td> <td>0.0% 🥇 39</td> <td>48.8% 108928</td> <td>9.3% 20713</td> <td>18.6% 41507</td> </tr> <tr> <td>Errors strict</td> <td>8.9% 🥇 19940</td> <td>69.9% 156081</td> <td>60.9% 136069</td> <td>40.1% 89519</td> </tr> <tr> <td>Time</td> <td>48s · 50s · 46s · 88s</td> <td>12s</td> <td>81s(*)</td> <td>512s(*)</td> </tr> <tr><td colspan="6"></td></tr> <tr> <td rowspan="3">coverage1k vyper 38278 functions</td> <td>Errors</td> <td>0.1% 🥇 34</td> <td>100.0% 38278</td> <td>96.2% 36814</td> <td>100.0% 38278</td> </tr> <tr> <td>Errors strict</td> <td>1.2% 🥇 441</td> <td>100.0% 38278</td> <td>98.4% 37650</td> <td>100.0% 38278</td> </tr> <tr> <td>Time</td> <td>45s · 39s · 44s · 89s</td> <td>2.0s</td> <td>5.5s(*)</td> <td>12s(*)</td> </tr> </table>

Control Flow Graph

False Negatives - Valid blocks possibly incorrectly marked unreachable by CFG analysis. Lower count usually indicates better precision.

<table> <tr> <td></td> <td>evmole <a href="benchmark/providers/evmole-rs/">rs</a> · <a href="benchmark/providers/evmole-js/">js</a> · <a href="benchmark/providers/evmole-py/">py</a> · <a href="benchmark/providers/evmole-go/">go</a></td> <td><a href="benchmark/providers/ethersolve">ethersolve</a></td> <td><a href="benchmark/providers/evm-cfg">evm-cfg</a></td> <td><a href="benchmark/providers/sevm">sevm</a></td> <td><a href="benchmark/providers/heimdall-rs">heimdall-rs</a></td> <td><a href="benchmark/providers/evm-cfg-builder">evm-cfg-builder</a></td> </tr> <tr> <td>Basic Blocks</td> <td>92.8% 🥇 483212</td> <td>52.5% 273518</td> <td>58.6% 305248</td> <td>37.3% 194368</td> <td>32.6% 169980</td> <td>14.5% 75383</td> </tr> <tr> <td>False Negatives</td> <td>7.2% 🥇 37496</td> <td>47.5% 247190</td> <td>41.4% 215460</td> <td>62.7% 326340</td> <td>67.4% 350728</td> <td>85.5% 445325</td> </tr> <tr> <td>Time</td> <td>14s · 26s · 12s · 55s</td> <td>888s</td> <td>36s</td> <td>9.8s</td> <td>20s</td> <td>359s</td> </tr> </table>

dataset flow-challenge500, 500 contracts, 520,708 blocks

notes

See benchmark/README.md for the methodology and commands to reproduce these results

versions: evmole v0.9.3; <a href="https://github.com/shazow/whatsabi">whatsabi</a> v0.25.0; <a href="https://github.com/acuarica/evm">sevm</a> v0.7.4; <a href="https://github.com/g00dv1n/evm-hound-rs">evm-hound-rs</a> v0.1.4; <a href="https://github.com/Jon-Becker/heimdall-rs">heimdall-rs</a> v0.9.3

(*): sevm and heimdall-rs are full decompilers, not limited to extracting function selectors

How it works

EVMole uses symbolic execution with a custom EVM implementation to trace how CALLDATA flows through the bytecode:

This approach is more accurate than static pattern matching because it follows the actual execution paths the EVM would take, correctly handling complex dispatchers, proxy patterns, and compiler-specific optimizations from both Solidity and Vyper.

Talks

EVMole: function selectors and arguments from bytecode - BlockSplit 2024
EVMole: function selectors and arguments from bytecode - EthCC 2024
Reconstructing Control Flow Graphs from EVM Bytecode - ETHTaipei 2025
Reconstructing Control Flow Graphs from EVM Bytecode: Faster, Better, Stronger - EthCC 2025

License

MIT

Related MCP servers

SI

SisRUN Training Plan

Maintained

Read your SisRUN (appsisrun.com.br) training plan: prescribed workouts, pace/HR windows, structure

0

Python

MIT

View repository →

CE

CedarAI Data Depot

Active

Read-only Cedar ARMS railroad data via Cedar login for authorized carriers.

0

MIT

View repository →

AH

Aha.io

Active

Search, read and update Aha.io ideas, features, epics, releases, goals and comments

6

TypeScript

MIT

View repository →

TR

TrueNAS SCALE

Active

Inspect and manage TrueNAS SCALE storage, shares, apps and system state with your own API key

1

Go

MIT

View repository →

CE

CEDRUS

Active

Reasoning scaffolding that supercharges your small AI: an argument-mapping MCP server

0

Python

AGPL-3.0

View repository →

AG

Agent^Rider

Active

Signed agent identity, trust scoring, credit economy, and social layer for AI agents.

2

TypeScript

View repository →