README.md•3.87 kB
# ENS MCP Server
An MCP server that resolves, analyzes, and contextualizes ENS domain activity to empower Web3 agents with human-readable identity insights.
## 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.