Skip to main content
Glama

MCP Etherscan Server

An MCP (Model Context Protocol) server that provides Ethereum blockchain data tools via Etherscan's API. Features include checking ETH balances, viewing transaction history, tracking ERC20 transfers, fetching contract ABIs, monitoring gas prices, and resolving ENS names.

Features

  • Balance Checking: Get ETH balance for any Ethereum address

  • Transaction History: View recent transactions with detailed information

  • Token Transfers: Track ERC20 token transfers with token details

  • Contract ABI: Fetch smart contract ABIs for development

  • Contract Code: Fetch smart contract code for development

  • Gas Prices: Monitor current gas prices (Safe Low, Standard, Fast)

  • ENS Resolution: Resolve Ethereum addresses to ENS names

Related MCP server: MCP Etherscan Server

Prerequisites

Installation

Installing via Smithery

To install MCP Etherscan Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-etherscan-server --client claude
  1. Clone the repository:

git clone [your-repo-url]
cd mcp-etherscan-server
  1. Install dependencies:

npm install
  1. Create a .env file in the root directory:

ETHERSCAN_API_KEY=your_api_key_here
  1. Build the project:

npm run build

Running the Server

Start the server:

npm start

The server runs on stdio, making it compatible with MCP clients like Cursor and Claude Desktop.

How It Works

This server implements the Model Context Protocol (MCP) to provide tools for interacting with Ethereum blockchain data through Etherscan's API. Each tool is exposed as an MCP endpoint that can be called by compatible clients.

Available Tools

  1. check-balance

    • Input: Ethereum address

    • Output: ETH balance in both Wei and ETH

  2. get-transactions

    • Input: Ethereum address, optional limit

    • Output: Recent transactions with timestamps, values, and addresses

  3. get-token-transfers

    • Input: Ethereum address, optional limit

    • Output: Recent ERC20 token transfers with token details

  4. get-contract-abi

    • Input: Contract address

    • Output: Contract ABI in JSON format

  5. get-contract-code

    • Input: Contract address

    • Output: Contract code in string format

  6. get-gas-prices

    • Input: None

    • Output: Current gas prices in Gwei

  7. get-ens-name

    • Input: Ethereum address

    • Output: Associated ENS name if available

Using with Cursor

To add this server to Cursor:

  1. Open Cursor and go to Cursor settings -> MCP

  2. Select the option to either add the MCP Server locally or globally, which will open a JSON configuration file.

  3. Add the configuration details. You can either add the MCP server via Smithery or via this repo locally:

    Smithery

    Using smithery.ai (This step requires a smithery.ai account)

    1. Navigate to this URL in your web browser: https://smithery.ai/server/@ThirdGuard/mcp-etherscan-server

    2. Enter your Etherscan API key in the field etherscanApiKey and click the connect button

    3. Navigate to the Cursor tab, copy the command, and run it in your terminal.

    Manual

    Paste the following configuration in the JSON file and replace ETHERSCAN-API-KEY-HERE with your Etherscan API key:

    {
      "Etherscan Tools": {
        "command": "npx",
        "args": [
          "-y",
          "@smithery/cli@latest",
          "run",
          "@ThirdGuard/mcp-etherscan-server",
          "--config",
          "\"{\\\"etherscanApiKey\\\":\\\"ETHERSCAN-API-KEY-HERE\\\"}\""
        ]
      }
    }

    Local

    Paste the following configuration in the JSON file and replace ABSOLUTE-PATH-HERE/mcp-etherscan-server/start.sh with the absolute path to the start.sh in this repo:

    {
      "Etherscan Tools (local)": {
        "command": "ABSOLUTE-PATH-HERE/mcp-etherscan-server/start.sh",
        "args": []
      }
    }
  4. Save the configuration

  5. The Etherscan tools will now be available in your Cursor AI conversations

Example Usage in Cursor

You can use commands like:

Check the balance of 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

or

Get the code of this smart contract: 0xdAC17F958D2ee523a2206206994597C13D831ec7 (USDT)

Development

To add new features or modify existing ones:

  1. The main server logic is in src/server.ts

  2. Etherscan API interactions are handled in src/services/etherscanService.ts

  3. Run npm run build after making changes

License

MIT License - See LICENSE file for details

Available Tools

7 tools
check-balanceB

Check the ETH balance of an Ethereum address

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesEthereum address (0x format)

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It only states a read operation, but fails to disclose return format, units, rate limits, or other behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no waste. It is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool's simplicity, the description lacks information about return values (e.g., unit of balance), error cases, or any operational context. It is minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds no meaning beyond what the schema already provides for the address parameter. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks the ETH balance of an Ethereum address, with a specific verb and resource. It distinguishes from siblings like get-contract-abi or get-ens-name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor any when-not-to-use scenarios. A single sentence lacks context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-contract-abiC

Get the ABI for a smart contract

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesContract address (0x format)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries full burden. It fails to disclose behaviors like what happens if the address is not a contract, network requirements, or whether the ABI is returned as JSON. This is insufficient for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. However, it could benefit from slight expansion to include return format, which would improve completeness without harming conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description should explain what the tool returns (e.g., JSON ABI array). It also lacks error states or network context. This is inadequate for a tool interacting with smart contracts.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter 'address', which is described with a pattern. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and the resource ('ABI for a smart contract'), making the tool's purpose easily understandable. It distinguishes from siblings which handle balances, ENS names, gas prices, transfers, and transactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives or what prerequisites are needed (e.g., contract must be verified or on a supported network). The sibling tools are unrelated, but lack of any usage context reduces score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-contract-codeC

Get the source code for a smart contract

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesContract address (0x format)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what the tool does but doesn't describe how it behaves: no information on permissions needed, rate limits, error conditions (e.g., invalid addresses), output format (e.g., raw code, metadata), or whether it's a read-only operation. This leaves significant gaps for safe and effective use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. It is front-loaded with the core purpose ('Get the source code'), making it easy to scan and understand quickly. Every part of the sentence contributes directly to explaining the tool's function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of retrieving smart contract code (which may involve blockchain interactions, authentication, or formatting), the description is insufficient. With no annotations and no output schema, it doesn't cover behavioral aspects like error handling, response structure, or limitations. The description alone doesn't provide enough context for reliable agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the 'address' parameter fully documented in the schema (including format and pattern). The description adds no additional parameter semantics beyond implying the address is for a smart contract, which is already clear from the tool name. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and resource ('source code for a smart contract'), making the purpose immediately understandable. It distinguishes from siblings like 'get-contract-abi' (which retrieves ABI) and 'get-transactions' (which retrieves transaction data). However, it doesn't specify the verb tense or scope details like whether it retrieves all source code or specific versions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a contract address), exclusions (e.g., not for non-contract addresses), or comparisons with siblings like 'get-contract-abi' for interface data. The agent must infer usage from the name and schema alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-ens-nameB

Get the ENS name for an Ethereum address

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesEthereum address (0x format)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only states a read operation. It does not disclose potential failures (e.g., whether it returns null for addresses without ENS names), network dependencies, or any side effects. Minimal behavioral context beyond the obvious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that conveys the core action and object. Every word is functional; there is no fluff or redundancy. It is optimally concise for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description covers the essential purpose but omits details about the return value format, potential errors, or whether it resolves primary ENS names. It is minimally adequate but leaves gaps for an agent unfamiliar with ENS.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% as the single parameter 'address' has a description, pattern, and type. The description adds no extra meaning beyond restating the parameter's purpose ('for an Ethereum address'). It does not provide examples or clarify format nuances beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and resource ('ENS name') combined with a clear target ('Ethereum address'). It clearly distinguishes from sibling tools which deal with balances, ABIs, gas, transfers, and transactions, leaving no ambiguity about the tool's function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context where this tool is preferred, leaving the agent to infer usage solely from the name and siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-gas-pricesA

Get current gas prices in Gwei

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the description omits behavioral details like data freshness, polling limits, or whether it returns a single value or multiple fee levels. For a zero-parameter tool, the description carries full burden and leaves ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise single sentence, no wasted words. However, could have added output format without harming conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite low complexity and no parameters, the lack of output schema means the description should clarify what 'gas prices' includes (e.g., low/avg/high). Fails to fully inform an agent about return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. No additional param info needed; the description appropriately has no redundant details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (get), the resource (current gas prices), and the unit (Gwei). It effectively distinguishes from sibling tools like check-balance or get-transactions, which are unrelated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use or alternatives, but the tool's simplicity and unique purpose among siblings make usage straightforward. Lacks when-not or context for multi-fee levels.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-token-transfersC

Get ERC20 token transfers for an Ethereum address

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesEthereum address (0x format)
limitNoNumber of transfers to return (max 100)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, and the description fails to disclose important behavioral details such as pagination, ordering, or whether the result includes all transfers or only recent ones.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence and front-loaded, but lacks important context. It is not overly verbose, but could be more informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple nature of the tool and the presence of schema descriptions for both parameters, the description is minimally adequate. However, it does not cover aspects like return format or usage constraints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline score of 3 applies. The description adds no additional meaning beyond the already documented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool retrieves ERC20 token transfers for a given Ethereum address. It is specific about the resource and action, but does not differentiate from siblings like get-transactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as get-transactions or check-balance. The description lacks context for appropriate usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-transactionsB

Get recent transactions for an Ethereum address

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesEthereum address (0x format)
limitNoNumber of transactions to return (max 100)

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only states 'Get recent transactions' without specifying behavior like pagination, rate limits, confirmation status, or what constitutes 'recent'. This leaves key behavioral traits unaddressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-front-loaded sentence that conveys the purpose without fluff. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the simple interface, the lack of output schema and behavioral details means the description does not sufficiently inform an agent about what data to expect or how to handle results, leaving it incomplete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All parameters are described in the input schema with 100% coverage. The description adds no extra semantic meaning beyond the schema, aligning with the baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and resource ('recent transactions for an Ethereum address'), immediately distinguishing it from siblings like 'check-balance' or 'get-token-transfers'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as 'get-token-transfers' for token-specific data or 'check-balance' for balances. Context for appropriate selection is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.0.0
    • First observedcheck-balance
    • First observedget-contract-abi
    • First observedget-contract-code
    • First observedget-ens-name
    • First observedget-gas-prices
    • First observedget-token-transfers
    • First observedget-transactions

TDQS

A3.5/5.0

Scored across 7 tools

Disambiguation5/5

Every tool has a clearly distinct purpose targeting specific Ethereum-related operations: balance checking, contract ABI/code retrieval, ENS resolution, gas price fetching, token transfer history, and transaction history. No overlap exists between these functions, making tool selection straightforward for an agent.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with hyphens (e.g., check-balance, get-contract-abi, get-ens-name). The naming is uniform across all seven tools, using clear action verbs like 'check' and 'get' paired with specific nouns.

Tool Count5/5

Seven tools is well-scoped for an Etherscan server, covering essential Ethereum blockchain interactions without being overwhelming. Each tool serves a distinct and useful purpose, such as balance checks, contract data retrieval, and transaction history, making the count appropriate for the domain.

Completeness4/5

The tool set provides strong coverage for common Ethereum queries, including balance, contract details, ENS, gas prices, and transaction histories. A minor gap exists in write operations (e.g., sending transactions or interacting with contracts), but for a read-focused server, this is reasonable and agents can work around it.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers