Which integrations are available for this server?

Uses Alchemy RPC endpoints to interact with blockchain networks for enhanced performance and reliability when executing Hats Protocol operations Provides comprehensive tools for managing Hats Protocol operations on Ethereum, including role management, permission checking, organizational structures, and analytics Utilizes GraphQL subgraph endpoints to query indexed Hats Protocol data, enabling efficient searching, filtering, and analytics of organizational structures and role assignments Facilitates Hats Protocol operations on Optimism, allowing users to manage hierarchical organizational structures and role-based permissions Enables Hats Protocol role management and organizational operations on the Polygon network, supporting hat creation, minting, burning, and permission verification

How do I use Hats Protocol MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hats Protocol MCP Server check if 0x742C3cF9Af45f91B109a81EfEaf11535ECDe9571 has admin role on Base" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Related MCP server: SettleMint

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