ETH Security MCP

A collection of MCP servers for security analysts, auditors, and incident response.

Setup

Dependencies

eth-security-mcp requires the following dependencies to be installed:

- node and npm
- just

Environment Variables Setup

MCP servers within eth-security-mcp may make use of environment variables in order to pass information such as API keys. The .env.example lists the relevant values that will be necessary in order to run all MCP severs. To setup your .env file, run cp .env.example .env and fill in the relevant information.

Workspaces

This repository uses npm workspaces to separate each action. To interact with a specific workspace use npm <action> -w src/<directory-name>.

Build And Debug

This repo uses a justfile to automate building and debugging using the MCP Inspector. For example, to build and debug the dune MCP server, you can run the following:

$ just -l
Available recipes:
    build workspace
    debug workspace
$ just debug dune

Installing MCP Servers Into Claude Desktop

To install MCP servers from this repo into Claude Desktop:

1. Run just setup-<machine> <mcp-server> where machine is either linux or macos, and mcp-server is the name of the directory that contains the MCP server you want to install.
2. The just command will produce a file in the directory of the MCP server called claude.config.tmp.json, which can be copy-pasted into the following file under mcpServers:

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- linux: ~/.config/Claude/claude_desktop_config.json

3. Once the config info has been added, restart Claude Desktop for the changes to take effect.

MCP Servers

This collection includes three specialized MCP servers for Ethereum security analysis:

| Server | Purpose | Tools |
|--------|---------|-------|
| Dune | Transaction analysis and blockchain data | get_transactions_by_address, get_activity_by_address |
| Sources | Function signatures and contract source code | retrieve_function_signature, retrieve_source_code |
| Cast | Transaction simulation and debugging | run_transaction |

🔍 Dune

Purpose: Access Dune API endpoints for structured transaction analysis and blockchain data retrieval.

Tools

get_transactions_by_address

Description: Retrieve transactions for a specific address using Dune's Sim API.

Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| address | string | ✅ | The address to get transactions for |
| block_number | number | ❌ | Filter transactions from this block number onwards |
| chain_ids | string | ❌ | Comma-separated list of chain IDs |
| is_sender | boolean | ❌ | Return transactions where address is the sender |
| is_receiver | boolean | ❌ | Return transactions where address is the receiver |

Returns

Returns an array of transaction objects with the following structure:

{
  address: string;          // Contract or account address
  block_number: number;     // Block containing the transaction
  data: string;             // Raw transaction data
  from: string;             // Transaction sender address
  to: string | null;        // Transaction recipient (null for contract creation)
  value: string;            // ETH amount transferred in wei
  logs: Array<{             // Event logs emitted during execution
    address: string;        // Contract emitting the event
    data: string;           // Raw event data
    topics: string[];       // Event topics
  }>;
}[]

get_activity_by_address

Description: Retrieve token activity for a specific address using Dune's Sim API.

Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| address | string | ✅ | The address to get token activity for |
| block_number | number | ✅ | Return activities up to this block number |
| chain_ids | string | ❌ | Comma-separated list of chain IDs |

Returns

Returns an array of activity objects with the following structure:

{
  chain_id: number;         // Chain ID where activity occurred
  block_number: number;     // Block containing the activity
  block_time: string;       // Timestamp of the block
  tx_hash: string;          // Transaction hash
  type: string;             // Type of activity (transfer, swap, etc.)
  asset_type: string;       // Type of asset (erc20, native, etc.)
  token_address: string;    // Address of the token contract
  from: string;             // Sender address
  to: string;               // Receiver address
  spender: string;          // Spender address (for approvals)
  value: string;            // Amount transferred
  value_usd: number;        // USD value of the transfer
  token_metadata: {         // Token information
    symbol: string;         // Token symbol
    decimals: number;       // Token decimals
    name: string;           // Token name
    price_usd: number;      // Token price in USD
    standard: string;       // Token standard (erc20, etc.)
  };
  function: {               // Function call details
    signature: string;      // Function signature
    name: string;           // Function name
    inputs: {               // Function inputs
      name: string;         // Parameter name
      type: string;         // Parameter type
      value: string;        // Parameter value
    };
  };
  contract_metadata: {      // Contract information
    name: string;           // Contract name
  };
  from_token_address: string;    // Source token address (for swaps)
  from_token_value: string;      // Source token amount (for swaps)
  to_token_address: string;      // Destination token address (for swaps)
  to_token_value: string;        // Destination token amount (for swaps)
}[]

📚 Sources

Purpose: Access function signature data and contract source code for security analysis.

Tools

retrieve_function_signature

Description: Retrieve function signature(s) for a given function selector from the 4byte API.

Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| selector | string | ✅ | Hexadecimal function selector (e.g., "0x70a08231") |

Returns

{
  best_match: string;      // Most likely function signature (lowest ID)
  all_matches: string[];   // All potential matching signatures
}

retrieve_source_code

Description: Retrieve source code for a contract address from Sourcify.

Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| address | string | ✅ | Contract address to retrieve source for |
| chain_id | number | ✅ | Chain ID where contract is deployed |

Returns

{
  sources: Record<string, {      // Source files
    [filePath: string]: string;  // File path → file content
  }>;
}

⚡ Cast

Purpose: Access Foundry's cast command-line tool for transaction simulation and smart contract interaction.

Tools

run_transaction

Description: Simulate a transaction using Foundry's cast run command for debugging and analysis.

Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| transactionHash | string | ✅ | Hash of the transaction to simulate |
| rpcUrl | string | ✅ | RPC URL of the Ethereum node |
| quick | boolean | ❌ | Use quick mode for faster simulation (default: false) |

Returns

Returns a string containing:
- Transaction execution details
- State changes
- Gas usage information
- Revert reasons (if transaction fails)