EVM Chain Interaction Gateway MCP

This repository furnishes an MCP server, engineered to grant Claude programmatic control over EVM-compatible networks leveraging the robust capabilities of ethers.js version 5. The service empowers Claude to execute critical blockchain operations such as deterministic wallet genesis, balance retrieval, transaction submission, and direct engagement with deployed smart contracts across any EVM environment.

Operational Toolset Summary

The gateway exposes the following distinct functionalities to the orchestrating agent (Claude):

Key Management & Instantiation

• wallet_create_random: Generates a new cryptographic wallet from a randomly derived private key.
• wallet_from_private_key: Establishes a wallet instance utilizing a provided secret key.
• wallet_from_mnemonic: Reconstitutes a wallet instance from a seed phrase.
• wallet_from_encrypted_json: Decrypts and loads a wallet stored in an encrypted JSON file format.
• wallet_encrypt: Secures an active wallet instance using a designated passphrase.

Wallet State Retrieval

• wallet_get_address: Obtains the public address associated with the active wallet.
• wallet_get_public_key: Fetches the uncompressed public key of the account.
• wallet_get_private_key: Retrieves the sensitive private key (use with extreme caution and security protocols).
• wallet_get_mnemonic: Returns the seed phrase for the wallet, if originally imported or generated this way.

On-Chain Data Fetching

• wallet_get_balance: Queries the native asset balance for the wallet address.
• wallet_get_chain_id: Determines the unique identifier of the current blockchain network.
• wallet_get_gas_price: Retrieves the prevailing network fee data for transaction estimation.
• wallet_get_transaction_count: Fetches the sequential nonce for outgoing transactions from the address.
• wallet_call: Executes a read-only smart contract method invocation without broadcasting a transaction.

Transaction Lifecycle Management

• wallet_send_transaction: Submits a constructed and signed transaction to the network for inclusion.
• wallet_sign_transaction: Digitally affixes the necessary signature to a transaction object internally, returning the raw signed payload.
• wallet_populate_transaction: Fills in necessary missing fields (like gas limits or chain ID) for a partially defined transaction object.

Cryptographic Verification

• wallet_sign_message: Generates a digital signature for arbitrary byte data.
• wallet_sign_typed_data: Creates a signature for structured data conforming to the EIP-712 standard.
• wallet_verify_message: Confirms the authenticity of a message signature against a public key.
• wallet_verify_typed_data: Validates a signature against structured EIP-712 data.

Data Provider Utilities

• provider_get_block: Retrieves detailed information for a specific block (by height or hash).
• provider_get_transaction: Fetches the full details of a transaction based on its hash.
• provider_get_transaction_receipt: Obtains the confirmation status and execution results of a confirmed transaction.
• provider_get_code: Reads the deployed bytecode from a given contract address.
• provider_get_storage_at: Looks up a specific storage slot value associated with a contract address.
• provider_estimate_gas: Calculates the probable computational cost (gas) for a proposed operation.
• provider_get_logs: Queries historical event logs matching specified filtering criteria.
• provider_get_ens_resolver: Retrieves the designated resolver contract for an Ethereum Name Service (ENS) domain.
• provider_lookup_address: Maps a blockchain address back to its registered ENS domain name.
• provider_resolve_name: Translates a human-readable ENS domain name into its corresponding EVM address.

Network & Fee Data

• network_get_network: Reports the descriptive parameters of the currently connected network.
• network_get_block_number: Fetches the height of the most recently mined block.
• network_get_fee_data: Retrieves dynamic fee components relevant for L1/EIP-1559 chains (base fee, priority fee, etc.).

Required Dependencies

• Node.js (Version 16 or newer runtime environment).
• The Claude Desktop client application.

Deployment Instructions

Method A: Direct Execution via npx (Recommended)

Execute the server immediately without persistent installation:

bash npx @mcp-dockmaster/mcp-cryptowallet-evm

This command pulls and runs the latest server package from the npm registry.

Method B: Manual Setup

1. Obtain the source code repository: bash git clone https://github.com/dcSpark/mcp-cryptowallet-evm.git cd mcp-cryptowallet-evm

2. Install necessary package dependencies: bash npm ci

3. Compile the source files: bash npm run build

Configuration Details

Environment Variables

Configuration can be optionally influenced via environment settings:

• PRIVATE_KEY: An optional setting to pre-load a specific private key for operations when no wallet context is explicitly passed to the tool calls.

Integrating with Claude Desktop

To enable Claude Desktop to discover and utilize this service:

1. Launch the Claude Desktop application.
2. Locate and open the primary configuration artifact:
3. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
4. Windows: %APPDATA%\Claude\claude_desktop_config.json

5. Linux: ~/.config/Claude/claude_desktop_config.json

6. Inject the server definition into the mcpServers object:

If running via npx:

{ "mcpServers": { "mcp-evm-gateway-service": { "command": "npx", "args": [ "@mcp-dockmaster/mcp-cryptowallet-evm" ] } } }

If using a locally compiled version:

{ "mcpServers": { "mcp-evm-gateway-service": { "command": "node", "args": [ "/path/to/your/mcp-cryptowallet-evm/build/index.js" ] } } }

After modification, a restart of the Claude Desktop client is required.

Local Execution Command

Start the server manually from the project root after building:

bash node build/index.js

Practical Application Examples

Once integrated, Claude gains direct blockchain proficiency. Examples of prompts include:

1. Generating a fresh key pair:

Please establish a brand new Ethereum key pair for me.

1. Checking Ether holdings:

Query the current balance denominated in ETH for the address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e.

1. Initiating a transfer:

Facilitate the transmission of 0.1 ETH from my configured wallet to address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e.

Claude abstracts the RPC communication, using this MCP gateway to execute ledger operations.

Development Guidelines

Extending Tool Functionality

To incorporate novel functionalities into this service:

1. Declare the new function signature within src/tools.ts.
2. Implement the corresponding execution logic within the appropriate handler module.
3. Register the new handler within the handlers mapping structure in src/tools.ts.

Build Process

Execute the compilation command:

bash npm run build

Licensing

Distributed under the MIT License.

WIKIPEDIA: XMLHttpRequest (XHR) is an API implemented as a JavaScript object whose methods are designed to dispatch HTTP requests from a web browser environment to a remote server. These methods grant browser-based applications the capability to transmit requests post-page-load completion and subsequently retrieve information. XMLHttpRequest forms the fundamental basis of Ajax programming techniques. Before Ajax gained prominence, server interaction was predominantly managed via traditional page reloads triggered by hyperlink navigation or form submissions. This often resulted in the replacement of the entire current view.

== Chronology == The foundational concept underpinning XMLHttpRequest was devised in the year 2000 by the development team at Microsoft Outlook. This concept was subsequently integrated into Internet Explorer version 5 (released in 1999). It should be noted that the initial implementation did not utilize the canonical XMLHttpRequest identifier; instead, developers relied on instantiating objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 was released (2006), broad support for the standardized XMLHttpRequest identifier was established across the browser landscape. The XMLHttpRequest identifier has since become the universally accepted convention across all major browser engines, including Mozilla's Gecko (since 2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published its initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 specification was released by the W3C on February 25, 2008, introducing functionalities such as progress event monitoring, enablement of cross-site requests, and improved handling for byte streams. By the conclusion of 2011, the enhancements defined in the Level 2 specification were merged back into the primary specification document. Development responsibilities transitioned to the WHATWG near the end of 2012, which now maintains the living document using Web IDL specifications.

== Operational Flow == Generally, invoking a request using XMLHttpRequest necessitates adherence to several sequential programming stages:

1. Object Instantiation: Create an instance of the XMLHttpRequest object via its constructor call.
2. Request Configuration: Invoke the open method to define the request method (GET/POST, etc.), specify the target Uniform Resource Identifier (URI), and select either synchronous or asynchronous execution mode.
3. Asynchronous Listener Setup: For non-blocking operations, register an event handler function designed to trigger upon changes in the request state.
4. Transmission: Initiate the request process by calling the send method, potentially passing payload data.
5. Response Handling: Monitor state transitions within the registered event listener. Upon successful completion (state transitions to 4, the 'done' state), the received server data is typically accessible via the responseText property.

Beyond these fundamental steps, XMLHttpRequest offers extensive configuration possibilities for request control and response parsing. Custom headers can be injected to guide server behavior. Data can be uploaded dynamically through the argument passed to the send call. The server response, if formatted in JSON, can be parsed directly into a usable JavaScript structure, or processed incrementally as data chunks arrive rather than waiting for the entire payload. Furthermore, requests can be terminated prematurely or subjected to a timeout limit to prevent indefinite waiting.

== Cross-Origin Communication Issues ==

During the nascent period of the World Wide Web, restrictions were implemented that prevented scripts loaded from one domain from directly accessing resources on a different domain, an issue termed the Same-Origin Policy. This limitation was identified early on as a significant impediment to building interactive applications. The early implementation of XMLHttpRequest did not natively bypass this restriction. Over time, mechanisms like CORS (Cross-Origin Resource Sharing) headers were introduced to explicitly permit controlled cross-domain data exchange via XMLHttpRequest.