Unlock-MCP

Unlock MCP is an MCP server that provides comprehensive access to Unlock Protocol on Base and Base-Sepolia networks. This server exposes a number of public read and write functions from the Unlock Protocol smart contracts, enabling AI agents to interact with membership, subscription, and access control functionality.

🚀 Features

Complete Function Coverage

55 Tools: All public read and write functions from PublicLock contract plus essential Unlock protocol functions
PublicLock Functions: Complete coverage of membership, pricing, transfers, and access control
Unlock Protocol Functions: Lock creation, upgrades, and protocol information
Read Functions: Query membership status, pricing, metadata, configuration, and protocol info
Write Functions: Purchase keys, manage memberships, configure locks, create locks, and handle upgrades

Two Operating Modes

Mode	Key Location	Gas Payer	Transport	Use Case
`stdio`	Server `.env`	Server	stdio	Claude Desktop, MCP clients
`proxy`	Browser/Wallet	Client	HTTP/SSE	n8n, web applications

Enterprise Ready

✅ Comprehensive Input Validation with Zod schemas
✅ Proper Error Handling with detailed logging
✅ Type Safety throughout the codebase
✅ n8n Integration with dedicated endpoints
✅ Health Monitoring and graceful shutdown
✅ Extensive Documentation for all tools

📦 Quick Start

1. Installation

git clone <repo-url> unlock-mcp
cd unlock-mcp
npm install
cp .env.example .env

2. Configuration

Edit .env with your settings:

# Required: Choose RPC provider
INFURA_API_KEY=your_infura_project_id
# OR
ALCHEMY_API_KEY=your_alchemy_api_key

# Required: Unlock Protocol contract addresses
# Base Mainnet
UNLOCK_ADDRESS=0x1FF7e338d5E582138C46044dc238543Ce555C963
# Base Sepolia (for testing)
# UNLOCK_ADDRESS=0x84b9B910527Ad5C03A9Ca831909E21e236EA7b06

# Optional: Default lock address
LOCK_ADDRESS=0x...

# Required for stdio mode only
PRIVATE_KEY=0x...  # ⚠️ Use test wallet with minimal funds

3. Build

npm run build

4A. Run stdio Mode (Claude Desktop)

Start the server:

MCP_MODE=stdio node dist/index.js

Claude Desktop configuration:

{
  "mcpServers": {
    "unlock": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/unlock-mcp/dist/index.js"],
      "env": { "MCP_MODE": "stdio" }
    }
  }
}

4B. Run proxy Mode (n8n, HTTP APIs)

Start the server:

MCP_MODE=proxy node dist/index.js

For Claude Desktop with SSE:

{
  "mcpServers": {
    "unlock": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/unlock-mcp/dist/index.js"],
      "env": { "MCP_MODE": "proxy" },
      "transport": { 
        "type": "sse", 
        "url": "http://localhost:3000/sse" 
      }
    }
  }
}

🔧 n8n Integration

The proxy mode is optimized for n8n workflows with:

MCP Client Tool Node

# Install n8n community MCP node
npm install n8n-nodes-mcp

Available Endpoints

GET /tools - List all available MCP tools
POST /tools/call - Execute MCP tools with validation
GET /health - Health check and server status
GET /sse - Server-Sent Events for real-time connection
GET / - API documentation

Example n8n Workflow

Add MCP Client Tool node
Configure server URL: http://localhost:3000
Use tools like getHasValidKey, purchase, grantKeys, etc.

🛠️ Available Tools

📖 Read Functions (30 tools)

Unlock Protocol Information

chainIdRead - Get current network chain ID
unlockVersion - Get Unlock protocol version
governanceToken - Get UDT governance token address
getGlobalTokenSymbol - Get global token symbol
publicLockLatestVersion - Get latest lock template version

PublicLock ERC721 & Membership

balanceOf - Get number of keys owned
ownerOf - Get owner of specific token
tokenURI - Get metadata URI
totalSupply - Get total keys created
getHasValidKey - Check if address has valid key
isValidKey - Check if specific token is valid
keyExpirationTimestampFor - Get key expiration time

Lock Configuration

keyPrice - Get current key price
maxKeysPerAddress - Get max keys per address
maxNumberOfKeys - Get maximum total keys
expirationDuration - Get key validity duration
name/symbol - Get lock metadata
tokenAddress - Get payment token
transferFeeBasisPoints - Get transfer fee

Pricing & Fees

purchasePriceFor - Calculate purchase price
getCancelAndRefundValue - Get refund amount
getTransferFee - Calculate transfer fee

Access Control

owner - Get lock owner
isLockManager - Check manager status
hasRole - Check role permissions

✍️ Write Functions (27 tools)

Lock Creation & Management

createLock - Deploy new basic PublicLock contract
createUpgradeableLock - Deploy upgradeable lock with custom data
upgradeLock - Upgrade existing lock to new version

Key Management

purchase - Buy keys for recipients
grantKeys - Issue keys administratively
extend - Extend key duration
renewMembershipFor - Renew membership

Key Transfers

transferFrom - Transfer key ownership
approve - Approve address for transfer
lendKey/unlendKey - Temporary key lending
shareKey - Share key time with others

Lock Administration

updateKeyPricing - Change price and payment token
updateLockConfig - Modify lock settings
setLockMetadata - Update name, symbol, URI
withdraw - Extract funds from lock

Access Control

grantRole/revokeRole - Manage permissions
setOwner - Transfer ownership

Advanced Features

cancelAndRefund - Cancel with refund
setReferrerFee - Configure referral rewards
mergeKeys - Combine key durations

🔍 Example Usage

Get Protocol Information

# Get current protocol version
{
  "name": "unlockVersion",
  "arguments": {
    "chainId": 8453
  }
}

# Get UDT governance token address
{
  "name": "governanceToken",
  "arguments": {
    "chainId": 8453
  }
}

Create a New Lock

# Deploy basic lock
{
  "name": "createLock",
  "arguments": {
    "chainId": 8453,
    "_lockCreator": "0x...",
    "_expirationDuration": "31536000",
    "_tokenAddress": "0x0000000000000000000000000000000000000000",
    "_keyPrice": "1000000000000000000",
    "_maxNumberOfKeys": "100",
    "_lockName": "My Membership Lock"
  }
}

# Deploy upgradeable lock with custom initialization
{
  "name": "createUpgradeableLock",
  "arguments": {
    "chainId": 8453,
    "data": "0x..."
  }
}

Check Membership Status

{
  "name": "getHasValidKey",
  "arguments": {
    "chainId": 8453,
    "lockAddress": "0x...",
    "_keyOwner": "0x..."
  }
}

Purchase a Key

{
  "name": "purchase", 
  "arguments": {
    "chainId": 8453,
    "lockAddress": "0x...",
    "_values": ["1000000000000000000"],
    "_recipients": ["0x..."],
    "_referrers": ["0x0000000000000000000000000000000000000000"],
    "_keyManagers": ["0x..."],
    "_data": ["0x"]
  }
}

Upgrade an Existing Lock

{
  "name": "upgradeLock",
  "arguments": {
    "chainId": 8453,
    "lockAddress": "0x...",
    "version": "15"
  }
}

Grant Administrative Keys

{
  "name": "grantKeys",
  "arguments": {
    "chainId": 8453, 
    "lockAddress": "0x...",
    "_recipients": ["0x...", "0x..."],
    "_expirationTimestamps": ["1735689600", "1735689600"], 
    "_keyManagers": ["0x...", "0x..."]
  }
}

🏗️ Architecture

Validation Pipeline

Request → Zod Schema → Function Call → Result/Error

Error Handling

Input Validation: Comprehensive Zod schemas for all parameters
Network Errors: Automatic retry and detailed error messages
Transaction Failures: Clear error reporting with gas estimation
Logging: Structured logs with timestamps and context

Security Features

Environment variable validation
Address format verification
Role-based access control
Safe error handling without data leaks

📚 Environment Variables

Variable	Required	Description	Example
`MCP_MODE`	No	Operating mode	`stdio` or `proxy`
`INFURA_API_KEY`	Yes*	Infura project ID	`abc123...`
`ALCHEMY_API_KEY`	Yes*	Alchemy API key	`xyz789...`
`UNLOCK_ADDRESS`	Yes	Unlock factory address	`0x1FF7e338d5E5...`
`LOCK_ADDRESS`	No	Default lock address	`0x...`
`PRIVATE_KEY`	stdio only	Wallet private key	`0x...`
`PORT`	No	Proxy server port	`3000`

*Choose one RPC provider

🧪 Testing

Comprehensive Test Suite

This project includes a complete testing framework covering:

77 Tests across unit, integration, and E2E layers
Mock Blockchain Interactions for reliable testing
MCP Protocol Compliance verification
CI/CD Integration with GitHub Actions

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test suites
npm run test tests/unit          # Unit tests only
npm run test:integration         # Integration tests
npm run test:e2e                # End-to-end tests

# Watch mode for development
npm run test:watch

# Interactive UI
npm run test:ui

Test MCP Inspector

# Test with official MCP Inspector
npm run test:mcp

# Manual testing
npm run build
npx @modelcontextprotocol/inspector node dist/src/index.js

Health Check API (Proxy Mode)

# Health status
curl http://localhost:3000/health

# List all 55 tools
curl http://localhost:3000/tools

# Execute function
curl -X POST http://localhost:3000/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "keyPrice",
    "arguments": {
      "chainId": 8453,
      "lockAddress": "0x..."
    }
  }'

Test Coverage

Current test coverage includes:

Schema Validation: 100% coverage of all input validation
Tool Definitions: Complete verification of 55 tools
Function Categorization: Read vs write function classification
Contract Interactions: Mocked blockchain operations
Error Handling: Comprehensive error scenario testing

📋 Contract Addresses

Base Mainnet (Chain ID: 8453)

Unlock Protocol: 0x1FF7e338d5E582138C46044dc238543Ce555C963

Base Sepolia (Chain ID: 84532)

Unlock Protocol: 0x84b9B910527Ad5C03A9Ca831909E21e236EA7b06

🤝 Contributing

This implementation follows MCP best practices:

Type-safe function signatures
Comprehensive input validation
Detailed error handling
Extensive logging
Clear documentation

Perfect for building membership systems, subscription services, and access control mechanisms with AI assistance.

⚠️ Security Notice

Use test networks for development
Never commit private keys to version control
Use dedicated wallets with minimal funds
Validate all inputs in production environments
Monitor transaction costs and set appropriate limits

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

An MCP server providing comprehensive access to Unlock Protocol on Base and Base-Sepolia networks, enabling AI agents to interact with membership, subscription, and access control functionality.

Related MCP Servers

Supabase MCP Server
JoshuaRileyDev
A
security
F
license
A
quality
A Model Context Protocol (MCP) server that provides programmatic access to the Supabase Management API. This server allows AI models and other clients to manage Supabase projects and organizations through a standardized interface.
Last updated -
8
578
42
JavaScript
Armor Crypto MCPofficial
armorwallet
A
security
A
license
A
quality
An MCP server providing unified access to blockchain operations, bridging, swapping, and crypto trading strategies for AI agents.
Last updated -
20
177
Python
GPL 3.0
eClass MCP Server
sdi2200262
A
security
F
license
A
quality
An MCP server that enables AI agents to authenticate with and interact with Open eClass platform instances, supporting UoA's SSO authentication system for retrieving course information and performing basic platform operations.
Last updated -
4
5
Python
OpenAI API MCP Server
ag2-mcp-servers
-
security
F
license
-
quality
An auto-generated MCP server that enables interaction with the OpenAI API, allowing users to access OpenAI's models and capabilities through the Multi-Agent Conversation Protocol.
Last updated -
Python

View all related MCP servers

Unlock-MCP

🚀 Features

Complete Function Coverage

Two Operating Modes

Enterprise Ready

📦 Quick Start

1. Installation

2. Configuration

3. Build

4A. Run stdio Mode (Claude Desktop)

4B. Run proxy Mode (n8n, HTTP APIs)

🔧 n8n Integration

MCP Client Tool Node

Available Endpoints

Example n8n Workflow

🛠️ Available Tools

📖 Read Functions (30 tools)

Unlock Protocol Information

PublicLock ERC721 & Membership

Lock Configuration

Pricing & Fees

Access Control

✍️ Write Functions (27 tools)

Lock Creation & Management

Key Management

Key Transfers

Lock Administration

Access Control

Advanced Features

🔍 Example Usage

Get Protocol Information

Create a New Lock

Check Membership Status

Purchase a Key

Upgrade an Existing Lock

Grant Administrative Keys

🏗️ Architecture

Validation Pipeline

Error Handling

Security Features

📚 Environment Variables

🧪 Testing

Comprehensive Test Suite

Running Tests

Test MCP Inspector

Health Check API (Proxy Mode)

Test Coverage

📋 Contract Addresses

Base Mainnet (Chain ID: 8453)

Base Sepolia (Chain ID: 84532)

🤝 Contributing

⚠️ Security Notice

Related MCP Servers

Supabase MCP Server

Armor Crypto MCPofficial

eClass MCP Server

OpenAI API MCP Server

New MCP Servers

MCP directory API