# ENS MCP Server

An MCP server that resolves, analyzes, and contextualizes ENS domain activity to empower Web3 agents with human-readable identity insights.

![GitHub License](https://img.shields.io/github/license/kukapay/ens-mcp) 
![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
![Status](https://img.shields.io/badge/status-active-brightgreen.svg)

## Features

- **Resolve ENS Names**: Map ENS domains (e.g., `vitalik.eth`) to Ethereum addresses.
- **Detailed Domain Information**: Fetch comprehensive domain data, including address, owner, registrant, expiry, registration, wrapped domain, and resolver details.
- **Domain Event History**: Retrieve events like transfers, resolver changes, and name wrapping, with relevant addresses and timestamps.

## Requirements

- Python 3.10 or higher
- [uv](https://github.com/astral-sh/uv) (recommended for dependency management)
- A valid API key for The Graph.

## Installation

1. **Clone the Repository**:

   ```bash
   git clone https://github.com/kukapay/ens-mcp.git
   cd ens-mcp
   ```

2. **Install Dependencies**:

   ```bash
   uv sync
   ```

  
3. **Installing to Claude Desktop**:

    Install the server as a Claude Desktop application:
    ```bash
    uv run mcp install main.py --name "ens-mcp"
    ```

    Configuration file as a reference:

    ```json
    {
       "mcpServers": {
           "ens-mcp": {
               "command": "uv",
               "args": [ "--directory", "/path/to/ens-mcp", "run", "main.py" ],
               "env": { "THEGRAPH_API_KEY": "the_graph_api_key"}               
           }
       }
    }
    ```
    Replace `/path/to/ens-mcp` with your actual installation path, and `the_graph_api_key` with your API key from The Graph.
    
## Usage

### Tools

The server provides three MCP tools:

1. **resolve_ens_name(domain: str) -> str**

   Resolves an ENS domain to its Ethereum address.

   - **Input**: ENS domain (e.g., `vitalik.eth`)
   - **Output**: Ethereum address (e.g., `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`) or "None"

   Example:
   ```
   resolve_ens_name("vitalik.eth") -> "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
   ```

2. **get_domain_details(domain: str) -> str**

   Fetches detailed information about an ENS domain, including its address.

   - **Input**: ENS domain
   - **Output**: Formatted string with domain details (address, owner, registrant, expiry, etc.)

   Example Output:
   ```
   ENS Domain: vitalik.eth
   Address: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
   Label Name: vitalik
   Label Hash: 0x...
   Subdomain Count: 5
   Owner: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
   Registrant: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
   Wrapped Owner: None
   Expiry Date: 2025-10-31 00:00:00
   TTL: 0 seconds
   Is Migrated: true
   Created At: 2017-05-04 12:00:00
   Registration: Registration Date: 2017-05-04 12:00:00
   Registration Expiry: 2025-10-31 00:00:00
   Registration Cost: 1000000000000000 Wei
   Registrant: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
   Wrapped Domain: Not Wrapped
   Resolver: Resolver Address: 0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41
   Content Hash: None
   Text Records: email, url
   ```

3. **get_domain_events(domain: str) -> str**

   Retrieves events associated with an ENS domain.

   - **Input**: ENS domain
   - **Output**: Formatted string listing events (e.g., transfers, resolver changes)

   Example Output:
   ```
   Event: Transfer
   Block Number: 1234567
   Transaction ID: 0x...
   New Owner: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

   Event: NewResolver
   Block Number: 1234568
   Transaction ID: 0x...
   Resolver Address: 0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41
   Resolver Addr: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
   ```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.