MCP Etherscan Explorer Service

This Model Context Protocol (MCP) backend leverages Etherscan's Application Programming Interface (API) to furnish comprehensive insights into the Ethereum decentralized ledger. Capabilities include querying native coin holdings, fetching historical transaction logs, auditing ERC-20 token movements, retrieving smart contract source interface definitions, observing current network utilization metrics (gas), and resolving human-readable ENS addresses.

Core Functionalities

• Balance Query: Retrieve the native Ether (ETH) balance for any specified Ethereum public key.
• Transaction Log Retrieval: Obtain a chronological list of recent inbound and outbound transactions with associated details.
• Token Movement Audit: Track recent transfers of fungible tokens governed by the ERC20 standard, including associated metadata.
• Contract Interface Fetch: Download the Application Binary Interface (ABI) for deployed smart contracts, essential for development.
• Contract Bytecode Retrieval: Fetch the verified source code or compiled bytecode associated with a given contract address.
• Network Fee Monitoring: Provide real-time estimates for transaction costs across different priority levels (Slow, Standard, Rapid).
• ENS Resolution: Translate human-readable Ethereum Name Service domains (e.g., vitalik.eth) into their corresponding wallet addresses.

Operational Requirements

• Runtime Environment: Node.js version 18 or newer.
• Credential: A valid API key sourced from the official Etherscan portal (https://etherscan.io/apis).

Deployment Instructions

Automated Installation via Smithery

For streamlined integration with clients supporting Smithery integration (like Claude Desktop):

bash npx -y @smithery/cli install mcp-etherscan-server --client claude

Manual Setup

1. Obtain the source code repository:

bash git clone [your-repo-url] cd mcp-etherscan-server

1. Install necessary software packages:

bash npm install

1. Configure environment variables by creating a .env file in the root directory:

bash ETHERSCAN_API_KEY=your_actual_api_key

1. Compile the project assets:

bash npm run build

Launching the Backend

Initiate the service using the standard execution command:

bash npm start

This process binds the server to standard input/output (stdio), ensuring compatibility with MCP-aware applications such as Cursor and Claude Desktop.

Architectural Overview

This service operates by adhering to the Model Context Protocol (MCP), exposing distinct endpoints that interface with the Etherscan API for specific blockchain data retrieval operations.

Exposed Tool Endpoints

1. check-balance

2. Input: Ethereum Address Identifier

3. Output: Balance data expressed in both the base unit (Wei) and its converted denomination (ETH)

4. get-transactions

5. Input: Ethereum Address Identifier, optional parameter for result count cap

6. Output: A list of recent transaction records, including ledger timestamps, value transfers, and counterparty addresses.

7. get-token-transfers

8. Input: Ethereum Address Identifier, optional parameter for result count cap

9. Output: Recent ERC20 token transactions, detailing token identification and quantity.

10. get-contract-abi

11. Input: Deployed Contract Address

12. Output: The Application Binary Interface definition formatted as a JSON structure.

13. get-contract-code

14. Input: Deployed Contract Address

15. Output: The verified source code or compiled bytecode as a plaintext string.

16. get-gas-prices

17. Input: None required

18. Output: Current network fee estimates denominated in Gwei.

19. get-ens-name

20. Input: Ethereum Address Identifier
21. Output: The corresponding registered Ethereum Name Service record, if present.

Integration with Cursor IDE

To enable these capabilities within the Cursor development environment:

1. Navigate to Cursor settings -> MCP within the application interface.

2. Select the mechanism for adding a new server (local or global), which opens the configuration JSON file.

3. Insert the necessary configuration block. You have the option to configure via Smithery or a direct local path:

### Smithery Configuration

#### Using the Smithery Web Interface 1. Visit: https://smithery.ai/server/@ThirdGuard/mcp-etherscan-server

1. Input your Etherscan API key into the etherscanApiKey field and initiate the connection via the connect button.

2. Switch to the Cursor tab, copy the provided terminal command, and execute it.

#### Manual JSON Insertion Paste the following structure into the Cursor MCP settings file, substituting ETHERSCAN-API-KEY-HERE with your actual key:

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

### Local Path Configuration Paste this structure, replacing ABSOLUTE-PATH-HERE/mcp-etherscan-server/start.sh with the full filesystem path to the service startup script:

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

1. Persist the configuration file changes.
2. The Etherscan data tools will now be accessible within Cursor's interactive conversational features.

Interaction Examples in Cursor

Users can invoke functionality using natural language prompts such as:

What is the Ether balance for address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

or

Retrieve the deployed source code for the USDT contract at address 0xdAC17F958D2ee523a2206206994597C13D831ec7

Development Guidance

To implement new functionalities or modify existing API service calls:

1. Core processing logic resides in src/server.ts.
2. Etherscan API data interaction modules are located in src/services/etherscanService.ts.
3. Recompile the TypeScript files to JavaScript using npm run build after any source code modifications.

Licensing

This project is distributed under the terms of the MIT License. Consult the LICENSE file for specifics.