Hats Protocol MCP Server

A comprehensive Model Context Protocol (MCP) server for managing Hats Protocol operations including role management, permission checking, organizational structures, and analytics across multiple blockchain networks.

Features

Hat Management: Create, mint, burn, and transfer hats
Tree Operations: Manage hierarchical organizational structures
Permission Checking: Verify wearers, standing, and eligibility
Metadata Operations: Update hat details and properties
Query Tools: Search and filter hats using GraphQL subgraph
Analytics: Generate reports and track activity
Multi-Chain Support: Works across all Hats Protocol networks
External Signing: Prepare transactions for hardware wallet signing

Supported Networks

Mainnet

Ethereum
Polygon
Arbitrum One
Optimism
Base
Gnosis Chain

Testnet

Sepolia
Base Sepolia

Installation

# Clone the repository
git clone <repository-url>
cd mcp-hats-protocol-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Environment Variables

Copy .env.template to .env and configure:

# RPC Provider API Keys (optional - uses public endpoints if not provided)
ALCHEMY_API_KEY=your_key_here
INFURA_API_KEY=your_key_here

# Block Explorer API Keys (required for contract verification)
ETHERSCAN_API_KEY=your_key_here
POLYGONSCAN_API_KEY=your_key_here
# ... other explorer keys

API Key Management

You can also set API keys using the MCP tools:

{
  "tool": "set-api-key",
  "args": {
    "keyName": "ALCHEMY_API_KEY",
    "value": "your_key_here"
  }
}

Usage

Integrating with Claude Code

The easiest way to use this MCP server is to integrate it with Claude Code. After installing the server, add it to your Claude configuration:

Quick Setup

# Clone and install the server
git clone https://github.com/your-username/mcp-hats
cd mcp-hats
npm install
npm run build

# Add to Claude Code (with optional API key for better performance)
claude mcp add hats-protocol --env ALCHEMY_API_KEY=your_key_here -- node dist/index.js

Alternative Setup Methods

Option 1: Local Development (no build required)

claude mcp add hats-protocol --env ALCHEMY_API_KEY=your_key_here -- npx tsx src/index.ts

Option 2: Global NPM installation (if published)

claude mcp add hats-protocol --env ALCHEMY_API_KEY=your_key_here -- npx mcp-hats-protocol

Option 3: Team/Project Configuration

# For team sharing via .mcp.json
claude mcp add --scope project hats-protocol --env ALCHEMY_API_KEY=your_key_here -- node dist/index.js

# For user-wide access across all projects
claude mcp add --scope user hats-protocol --env ALCHEMY_API_KEY=your_key_here -- node dist/index.js

Managing the Integration

# List all MCP servers
claude mcp list

# View server details
claude mcp get hats-protocol

# Remove the server
claude mcp remove hats-protocol

Environment Variables in Claude Code

You can set API keys when adding the server:

claude mcp add hats-protocol \
  --env ALCHEMY_API_KEY=your_alchemy_key \
  --env ETHERSCAN_API_KEY=your_etherscan_key \
  -- node dist/index.js

Manual Server Usage

If you prefer to run the server manually (for development or standalone use):

# Development mode
npm run dev

# Production mode
npm start

Using with Claude Code

Once integrated, you can use the Hats Protocol tools directly in your conversations with Claude:

Example: Check if someone has a role

Check if address 0x742C3cF9Af45f91B109a81EfEaf11535ECDe9571 is wearing hat 0x0000000100010000000000000000000000000000000000000000000000000000 on Ethereum

Example: Create a new organization

Help me create a new DAO called "TechCollective" on Base Sepolia with myself (0x742C3cF9Af45f91B109a81EfEaf11535ECDe9571) as the founder

Example: Analyze organizational structure

Show me the organizational structure for tree 0x00000001 on Base and visualize it as an ASCII tree

Example: Get role assignment guidance

I need to assign the CTO role to a new team member. Can you guide me through the process and prepare the transaction?

Claude will automatically use the appropriate Hats Protocol tools and provide intelligent guidance through the built-in prompts and resources.

Available Tools

Hat Management

create-hat - Create a new hat in the hierarchy
mint-hat - Assign a hat to a wearer
burn-hat - Remove a hat from a wearer
transfer-hat - Transfer a hat between wearers

Permission Checking

check-hat-wearer - Verify if an address wears a specific hat
check-hat-standing - Check if a wearer is in good standing

Query Tools

get-hat-details - Get detailed information about a hat
query-hats-by-wearer - Get all hats worn by an address
get-tree-structure - Get hierarchical tree structure

Network Tools

list-networks - List all supported networks
set-api-key - Configure API keys

Example Commands

Create a Hat

{
  "tool": "create-hat",
  "args": {
    "networkName": "ethereum",
    "admin": "0x0000000100000000000000000000000000000000000000000000000000000000",
    "details": "Engineering Team Lead",
    "maxSupply": 1,
    "eligibility": "0x0000000000000000000000000000000000000000",
    "toggle": "0x0000000000000000000000000000000000000000",
    "mutable": true,
    "imageURI": "https://example.com/hat-image.png"
  }
}

Check Hat Wearer

{
  "tool": "check-hat-wearer",
  "args": {
    "networkName": "ethereum",
    "wearer": "0x742C3cF9Af45f91B109a81EfEaf11535ECDe9571",
    "hatId": "0x0000000100010000000000000000000000000000000000000000000000000000"
  }
}

Development

Project Structure

src/
├── index.ts           # Entry point
├── server.ts          # MCP server setup
├── types/             # TypeScript definitions
├── utils/             # Utility functions
├── networks/          # Network configurations
├── clients/           # Hats SDK and subgraph clients
├── tools/             # MCP tool implementations
└── resources/         # MCP resources

test/
├── unit/              # Unit tests
├── integration/       # Integration tests
└── e2e/              # End-to-end tests

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

Code Quality

# Type checking
npm run typecheck

# Linting
npm run lint

# Formatting
npm run format

Architecture

Core Components

MCP Server: Handles tool registration and request routing
Hats Client: Wrapper around Hats Protocol SDK
Subgraph Client: GraphQL client for querying indexed data
Network Manager: Multi-chain configuration and RPC management
Tool Implementations: Individual tools for specific operations

Data Flow

MCP client sends tool request → MCP server
Server validates input with Zod schemas
Tool implementation calls appropriate client method
Client interacts with blockchain or subgraph
Response formatted and returned to MCP client

Resources

Contributing

Create a feature branch
Write tests for new functionality
Ensure all tests pass
Submit pull request with detailed description

License

MIT