ENS Query Gateway Service

This specialized MCP Gateway allows Claude to execute complex operations against the Ethereum Name Service (ENS) ecosystem. It supports name-to-address translation, status checks, detailed record fetching, and registration cost estimation.

Official NPM Package Link: https://www.npmjs.com/package/mcp-server-ens

Available Endpoints (Tools)

resolveEthName

Translates a registered ENS identifier into its canonical Ethereum wallet address. - Input Requirements (Mandatory): - name (text): The fully qualified domain name (e.g., 'alice.eth'). - Output: - The corresponding hexadecimal Ethereum address or an explicit failure notification.

reverseMapAddress

Determines the preferred human-readable ENS name linked to a specific Ethereum public key. - Input Requirements (Mandatory): - address (text): The 42-character Ethereum address being inspected. - Output: - The associated ENS name, or confirmation that no reverse record exists.

fetchTextData

Retrieves specific, user-defined metadata associated with an ENS record, identified by a key. - Input Requirements (Mandatory): - name (text): The ENS domain under query. - key (text): The metadata field identifier (e.g., 'web3-email', 'homepage', 'avatar-uri'). - Output: - The content value for that specific key, or a null result if the record is absent.

checkRegistrationStatus

Assesses whether a desired ENS name slot is currently unregistered and open for claiming. - Input Requirements (Mandatory): - name (text): The candidate name for status evaluation. - Output: - The registration status, including current ownership details if already taken.

retrieveAllProfileData

Aggregates all known metadata, ownership structure, resolver configuration, and address pointers for a given domain. - Input Requirements (Mandatory): - name (text): The primary ENS domain to fully analyze. - Output: - A comprehensive data object detailing the resolver contract, all embedded text records, associated addresses, content hashing, and tenure information.

discoverSubdomains

Lists all immediate child domains registered under a specified parent ENS name. - Input Requirements (Mandatory): - name (text): The parent domain to enumerate. - Output: - A structured list of discovered subdomains, including their respective current owners.

queryNameTimeline

Generates a chronological sequence of significant state changes for an ENS name. - Input Requirements (Mandatory): - name (text): The domain whose historical ledger is requested. - Output: - A detailed log of events such as ownership transfers, resolver adjustments, and initial registration timestamps.

calculateRegistrationFee

Estimates the economic outlay required to secure a new ENS name registration. - Input Requirements (Mandatory): - name (text): The domain for which pricing is sought. - Input Preferences (Optional): - duration (integer, default is 1): The registration term length, specified in solar years. - **Output: - A breakdown of the required fees, encompassing the base cost, any premium if applicable, and the total required gas expenditure.

Deployment & Environment Configuration

Essential Prerequisites

• A functioning Node.js runtime environment (version 16 minimum).
• A package manager (npm or yarn).
• Valid access credentials or endpoints for connecting to Ethereum network nodes (RPC).

Initialization Steps

1. Obtain the source code repository: bash git clone https://github.com/JustaName-id/ens-mcp-server cd ens-mcp-server

2. Install necessary dependencies: bash npm install

3. Configure RPC Endpoint Settings: Create a .env file in the root directory to specify your preferred communication channels:

PROVIDER_URL=https://my.custom.rpc.endpoint,https://fallback.node.io

If this variable is omitted, the system defaults to a set of public access points: - https://eth.drpc.org - https://eth.llamarpc.com - https://ethereum.publicnode.com - https://rpc.ankr.com/eth

Integration with Claude Desktop Interface

To enable this service within your local Claude configuration file (claude_desktop_config.json):

Execution via npx

{ "mcpServers": { "ens_api": { "command": "npx", "args": [ "-y", "mcp-server-ens" ], "env": { "PROVIDER_URL": "https://your-provider-url.com,https://your-backup-provider.com" } } } }

Execution via Direct Node Invocation

{ "mcpServers": { "ens_api": { "command": "node", "args": [ "/absolute/path/to/your/server.js" ], "env": { "PROVIDER_URL": "https://your-provider-url.com,https://your-backup-provider.com" } } } }

Operational Resilience and Diagnostics

The gateway incorporates comprehensive error management: - Connection failure diagnostics for RPC layers. - Validation checks for malformed ENS names or invalid wallet identifiers. - Specific handling for protocol-level ENS exceptions. - General runtime error normalization to provide clear, actionable feedback.

Source Code Distribution

To upload the latest version to the public NPM registry: bash npm publish --access public

Troubleshooting Guidelines

Should operational issues arise, review the following: - Confirm the accessibility and functionality of your defined Ethereum RPC URLs. - Double-check the syntactic correctness of the ENS names or addresses you are querying. - Ensure the underlying ENS resolution libraries are current. - Utilize the PROVIDER_URL environment variable, populated with multiple endpoints separated by commas, to facilitate failover testing.

Legal Framework

This software package is released under the permissive MIT License terms. Full details regarding usage, alteration, and redistribution rights are documented within the accompanying LICENSE file in the project's source directory.