# ETHID MCP Server
An MCP (Model Context Protocol) server that provides comprehensive access to the Ethereum Follow Protocol (EFP) API, enabling social graph queries for Ethereum addresses and ENS names.
## Features
### Core Tools (22 Total)
- **Basic Operations**: `getFollowerCount`, `getFollowers`, `getFollowing`, `checkFollowing`, `checkFollower`
- **Profile Data**: `fetchAccount`, `fetchProfileStats`, `fetchProfileLists`, `fetchProfileBadges`, `fetchProfileQRCode`
- **Advanced Queries**: `fetchProfileFollowing`, `fetchProfileFollowers` with pagination and filtering
- **Tag Management**: `fetchFollowingTags`, `fetchFollowerTags` (limited availability)
- **Social Features**: `fetchFollowState`, `fetchNotifications`, `fetchRecommendations`, `fetchLeaderboard`
- **List Operations**: `fetchListState`, `fetchListsForUser`, `fetchPoapLink`
- **ENS Resolution**: `fetchBulkAccounts` - Bulk reverse resolution of addresses to ENS names
- **Help & Guidance**: `searchContexts`, `getBestPractices`, `getUsagePattern`, `getToolGuidance`, `getEfficiencyTips`
### Key Capabilities
- **Tag Filtering**: Filter followers/following by tags (e.g., "top8", "friend", "family")
- **ENS Resolution**: Automatic resolution of ENS names to addresses
- **Bulk ENS Reverse Resolution**: Convert multiple addresses to ENS names efficiently
- **Pagination Support**: Handle large datasets efficiently
- **Search Functionality**: Search within followers/following lists
- **Real-time Data**: Option to fetch fresh data bypassing cache
## Setup
### For Developers
```json
{
"mcpServers": {
"ethid-mcp": {
"command": "npx",
"args": ["mcp-remote", "https://ethid-mcp.efp.workers.dev/sse"]
}
}
}
```
## Usage
**🚀 IMPORTANT: Before using the ETHID MCP server, run the initialization prompt from [ETHID_MCP_INITIALIZATION_PROMPT.md](./ETHID_MCP_INITIALIZATION_PROMPT.md) to ensure optimal performance and proper tool usage.**
See [USAGE_GUIDE.md](./USAGE_GUIDE.md) for comprehensive examples and best practices.
### Quick Examples
```typescript
// Get follower count
await getFollowerCount({ addressOrName: 'vitalik.eth' });
// Result: "vitalik.eth has 4811 followers and is following 10 accounts."
// Check who someone follows with tags
await getFollowing({
addressOrName: 'efp.encrypteddegen.eth',
tags: ['top8'],
});
// Result: List of top 8 friends with their addresses and tags
// Convert addresses to ENS names
await fetchBulkAccounts({
addresses: ['0xd8da6bf26964af9d7eed9e03e53415d37aa96045', '0x849151d7d0bf1f34b70d5cad5149d28cc2308bf1'],
});
// Result: ["vitalik.eth", "jesse.xyz"]
// Get profile information
await fetchAccount({ addressOrName: 'brantly.eth' });
// Result: Complete profile with ENS records, avatar, social links
```
## Project Structure
```
ethid-mcp/
├── src/
│ ├── index.ts # Main MCP agent implementation
│ ├── tools/ # Modular tool definitions
│ │ ├── index.ts # Tool registration coordinator
│ │ ├── profile.ts # Profile and following/followers tools
│ │ ├── account.ts # Account data and ENS resolution tools
│ │ ├── relationships.ts # Relationship checking tools
│ │ ├── tags.ts # Tag management tools
│ │ ├── discovery.ts # Discovery and recommendation tools
│ │ ├── lists.ts # List management tools
│ │ ├── context.ts # Documentation context search
│ │ └── guidance.ts # Best practices and guidance tools
│ ├── types/ # TypeScript types
│ │ ├── api.ts # API response types
│ │ └── env.ts # Environment configuration types
│ ├── contexts/ # Documentation contexts
│ └── utils/ # Utility functions
├── wrangler.json # Cloudflare Worker config
├── USAGE_GUIDE.md # Comprehensive usage guide
└── ETHID_MCP_INITIALIZATION_PROMPT.md # Initialization guide
```
## Architecture
The ETHID MCP server operates as a Cloudflare Worker that:
1. Receives MCP requests via the local proxy server
2. Calls the EFP API at `https://api.ethfollow.xyz/api/v1`
3. Returns formatted responses optimized for AI consumption
### Key Components
- **Cloudflare Worker**: Main API integration and business logic
- **Local MCP Server**: Proxy for Claude Desktop integration
- **Node.js Wrapper**: Compatibility layer for Node.js v22.12.0+
## Contributing
The project is actively maintained and welcomes contributions. The current deployment is fully functional with all tools working correctly.
## License
See [LICENSE](./LICENSE) for details.
