Unlock-MCP

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

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

1. Add MCP Client Tool node
2. Configure server URL: http://localhost:3000
3. 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

*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