Self MCP Server

MCP server for Self protocol integration assistance. Helps developers add privacy-preserving identity verification to their apps.

Features

• Core Self Protocol Tools: Integration guides, code generation, debugging assistance
• Tools.self.xyz Integration: Direct interaction with blockchain for reading configurations and generating hashes
• Web3 Integration: Read-only blockchain operations (no write operations to keep it free)
• Comprehensive Documentation: Resources and prompts for Self protocol development

Installation

Option 1: Install from GitHub (Recommended)

pip install git+https://github.com/selfxyz/self-mcp.git

After installation, run with: self-mcp

Option 2: Local Development Setup

1. Clone the repository:

git clone https://github.com/selfxyz/self-mcp.git
cd self-mcp

2. Create virtual environment:

python -m venv venv
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

3. Install dependencies:

cd self-mcp
pip install -e .

4. Verify installation:

python server.py  # Should start without errors

Configuration

For Claude Desktop

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "self-mcp": {
      "command": "/path/to/your/python",
      "args": [
        "/path/to/self-mcp/self-mcp/server.py"
      ],
      "cwd": "/path/to/self-mcp/self-mcp"
    }
  }
}

For Cursor

Create mcp.json in your project root:

Option 1: Using Python directly (simple)

{
  "mcpServers": {
    "self-mcp": {
      "command": "/path/to/your/python",
      "args": [
        "/path/to/self-mcp/self-mcp/server.py"
      ],
      "cwd": "/path/to/self-mcp/self-mcp"
    }
  }
}

Option 2: Using uv (recommended for dependency management)

{
  "mcpServers": {
    "self-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "--with", "web3",
        "--with", "aiohttp",
        "python",
        "/path/to/self-mcp/self-mcp/server.py"
      ],
      "cwd": "/path/to/self-mcp/self-mcp"
    }
  }
}

Replace /path/to/your/python with your Python interpreter path (e.g., /Users/nightmare/Projects/self-work/self-mcp/venv/bin/python) and /path/to/self-mcp with the actual path to your self-mcp directory.

Note: The cwd (current working directory) parameter sets the directory where the server process will run. This is important for relative file paths and ensuring the server finds its dependencies.

Then enable MCP in Cursor settings → cursor settings → Tools and Integrations → New MCP Server This will open mcp.json of cursor where you can put the above configuration.

Available Tools

Core Tools

1. explain_self_integration

Get integration guides for specific use cases.

• use_case: "airdrop" | "age-verification" | "humanity-check"

2. generate_verification_code

Generate code for Self integration.

• component: "frontend-qr" | "backend-verify" | "smart-contract"
• language: "typescript" | "javascript" | "solidity"

3. debug_verification_error

Debug Self verification errors.

• error_message: The error you're seeing
• context: Optional hint about error type

4. check_self_status

Check Self protocol network status and contracts.

• network: "celo-mainnet" | "celo-testnet"

5. generate_verification_config

Generate complete verification configuration.

• requirements: Dict with app settings

6. explain_sdk_setup

Understand SDK backend requirements.

• topic: "config-storage" | "user-id-type" | "attestation-ids" | "full-setup"

7. generate_eu_id_verification

Generate EU ID card verification code (V2).

• component: "frontend" | "backend" | "smart-contract"
• language: "typescript" | "javascript" | "solidity"

Tools.self.xyz Integration Tools

8. generate_scope_hash

Generate a deterministic scope hash for an address/URL and seed.

• address_or_url: The address or URL to hash
• scope_seed: The seed value for scope generation

9. generate_config_id

Generate a config ID from verification requirements and check blockchain existence.

• minimum_age: Optional minimum age requirement
• excluded_countries: Optional list of excluded country codes
• ofac_enabled: Optional list of OFAC check settings for each ID type
• network: "mainnet" | "testnet"

10. read_hub_config

Read configuration details from the Hub contract.

• config_id: The config ID to read
• network: "mainnet" | "testnet"

11. list_country_codes

List available country codes for verification configuration.

• search: Optional search term to filter countries

12. guide_to_tools

Generate a link to tools.self.xyz with pre-filled parameters.

• action: "deploy-config" | "connect-wallet" | "select-countries" | "generate-scope" | "read-config"
• parameters: Optional dict with pre-fill values

Example Usage

User: "How do I integrate Self for age verification?"
Assistant: [Provides step-by-step guide with code examples]

User: "Generate backend verification code in TypeScript"
Assistant: [Provides complete backend code with proper SDK setup]

User: "Explain config storage setup"
Assistant: [Shows IConfigStorage implementation examples]

Resources

• Contract Addresses: self://contracts/addresses
• Integration Examples: self://examples/{airdrop|age-gate}
• Best Practices: self://docs/best-practices

Prompts

• Design Flow: design-verification-flow
• Troubleshooting: troubleshoot-integration

Development

# Clone repo
git clone https://github.com/selfxyz/self-mcp.git
cd self-mcp

# Install in development mode
pip install -e .

# Run tests
python test_server.py

License

MIT