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

Related MCP server: Armor Crypto MCP

📦 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