MCP Ethereum Data Retrieval Service

An MCP (Model Context Protocol) middleware component leveraging Etherscan's Application Programming Interface (API) to supply comprehensive Ethereum blockchain telemetry. Core capabilities encompass querying native currency holdings, inspecting transaction histories, auditing token movements (ERC20), retrieving interface specifications for contracts, observing prevailing operational costs, and resolving decentralized names (ENS).

Key Capabilities

• Balance Scrutiny: Determine the native Ether balance associated with any specified Ethereum identifier.
• Transaction Log: Retrieve and display chronological records of recent ledger movements, including full details.
• Asset Flow Auditing: Trace recent ERC20 token transfers, complete with associated token metadata.
• Interface Fetching: Secure smart contract Application Binary Interfaces (ABIs) crucial for development operations.
• Source Code Retrieval: Obtain the underlying source code for deployed smart contracts.
• Operational Cost Tracking: Monitor prevailing network transaction fees (categorized as Low, Standard, Fast tiers).
• Domain Translation: Convert human-readable ENS names back to their canonical Ethereum addresses.

Prerequisites for Deployment

• Runtime environment: Node.js version 18 or newer.
• An active Etherscan API credential (available from https://etherscan.io/apis).

Deployment Instructions

Automated Installation via Smithery

For streamlined setup with Claude Desktop using Smithery:

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

1. Obtain the source repository:

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

1. Install required project dependencies:

bash npm install

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

bash ETHERSCAN_API_KEY=your_api_key_here

1. Compile the project assets:

bash npm run build

Service Execution

Initiate the server process:

bash npm start

The service communicates over standard input/output (stdio), ensuring compatibility with MCP-aware clients such as Cursor and Claude Desktop.

Operational Mechanics

This server implements the Model Context Protocol (MCP) specification to expose functions for interacting with Etherscan's data services. Each distinct operation is mapped to a specific MCP callable endpoint.

Exposed Utility Functions

1. check-balance

2. Input Parameter: An Ethereum wallet address.

3. Return Value: The calculated ETH balance, provided in both the base unit (Wei) and scaled units (ETH).

4. get-transactions

5. Input Parameter: An Ethereum address, optionally a count limit.

6. Return Value: A list of recent transactions detailing timestamps, value transfers, and involved addresses.

7. get-token-transfers

8. Input Parameter: An Ethereum address, optionally a count limit.

9. Return Value: A log of recent ERC20 asset movements, including specifics about the transferred token.

10. get-contract-abi

11. Input Parameter: A contract deployment address.

12. Return Value: The contract's Application Binary Interface, formatted as JSON.

13. get-contract-code

14. Input Parameter: A contract deployment address.

15. Return Value: The verified contract source code as a string.

16. get-gas-prices

17. Input Parameter: None required.

18. Return Value: Current network gas fee estimates expressed in Gwei.

19. get-ens-name

20. Input Parameter: An Ethereum address.
21. Return Value: The corresponding ENS domain name, if registered.

Integration with Cursor IDE

To integrate this service within the Cursor environment:

1. Navigate to Cursor settings and select the MCP section.

2. Choose the option to integrate the MCP Server either locally or globally, which opens the configuration file.

3. Populate the configuration object. Integration can utilize Smithery or local repository referencing:

### Smithery Path

#### Using smithery.ai 1. Access the service registration page: 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 configuration tab, copy the presented command, and execute it in your terminal.

#### Manual Configuration

Insert the subsequent configuration block into your JSON settings, 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

Paste the following configuration, replacing ABSOLUTE-PATH-HERE/mcp-etherscan-server/start.sh with the full path to the startup script in your local clone:

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

1. Save the configuration file changes.
2. The newly integrated Etherscan utilities will be accessible within Cursor's dialogue system.

Practical Examples within Cursor

Utilize queries such as:

Determine the Ether balance for address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

or

Retrieve the operational code for the contract 0xdAC17F958D2ee523a2206206994597C13D831ec7 (USDT token)

Development Guidelines

To introduce new functionalities or modify existing service routines:

1. Primary server logic resides in src/server.ts.
2. Etherscan API communication modules are located in src/services/etherscanService.ts.
3. Remember to execute npm run build after any source code modifications.

Licensing Information

This project is released under the MIT License. Refer to the LICENSE document for comprehensive details.