A Model Context Protocol (MCP) server for Privy.io - the Web3 wallet infrastructure platform. Provides comprehensive access to user management, wallet operations, and blockchain interactions through Claude and other MCP clients.

• Get User Details: Retrieve user information by Privy DID including linked accounts, MFA methods, and metadata
• List Users: Paginated listing of all users (default 50 per page)
• Search Users: Search for users by search term and optional identifiers (emails, phone numbers, wallet addresses)
• Query by Wallet: Find users by blockchain wallet address
• Create Users: Create new users with linked accounts (email, phone, wallet, OAuth providers)
• Delete Users: Remove users and associated data

• Get Wallet: Retrieve wallet details including address, chain type, and timestamps
• List Wallets: Paginated wallet listing with metadata
• Create Wallets: Generate wallets for users (Ethereum, Solana, Bitcoin, EVM-compatible chains)
• Wallet Balance: Check current wallet balances
• Transaction History: Retrieve wallet transaction history with pagination
• Update Wallets: Modify wallet metadata and configuration

• Python 3.10 or higher
• Privy.io account with API credentials

The easiest way to use this MCP server is with uvx, which automatically fetches the package from PyPI:

uvx privy-mcp-server

No installation needed! Configure your MCP client (see Usage below) and you're ready to go.

For local development:

1. Clone the repository:

git clone https://github.com/incentivai-io/privy-mcp-server.git
cd privy-mcp-server

2. Create virtual environment:

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

3. Install dependencies:

pip install -e .

4. Configure environment variables:

cp .env.example .env

Edit .env and add your Privy credentials:

PRIVY_APP_ID=your_app_id_here
PRIVY_APP_SECRET=your_app_secret_here

Get your credentials: Dashboard → App Settings → Basics on Privy.io

Run directly with Python:

python -m privy_mcp

Or use the MCP inspector for testing:

npx @modelcontextprotocol/inspector python -m privy_mcp

For example, from the project directory:

npx @modelcontextprotocol/inspector python -m privy_mcp

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "privy": {
      "command": "uvx",
      "args": ["privy-mcp-server"],
      "env": {
        "PRIVY_APP_ID": "your_app_id_here",
        "PRIVY_APP_SECRET": "your_app_secret_here"
      }
    }
  }
}

{
  "mcpServers": {
    "privy": {
      "command": "python",
      "args": ["-m", "privy_mcp"],
      "env": {
        "PRIVY_APP_ID": "your_app_id_here",
        "PRIVY_APP_SECRET": "your_app_secret_here"
      }
    }
  }
}

Restart Claude Desktop after configuration.

• get_user - Get user details by Privy DID. Returns user data including linked accounts (email, phone, wallet, OAuth providers), MFA methods, creation timestamps, terms acceptance, and custom metadata
• list_users - List all users with pagination support. Returns paginated list of users with their linked accounts, wallets, and metadata (default 50 per page)
• search_users - Search for users by search term and optional identifiers (emails, phone numbers, wallet addresses). Returns user data matching the search criteria including linked accounts, MFA methods, and metadata
• get_user_by_wallet - Query and retrieve user information by blockchain wallet address. Supports Ethereum, Solana, Bitcoin, and all EVM-compatible chains
• create_user - Create a new user with linked accounts. Supports email, phone, wallet, and 15+ OAuth providers (Apple, Discord, GitHub, Google, Farcaster, Telegram, Twitter, etc.). Optionally creates an embedded wallet
• delete_user - Delete a user by Privy DID. This action is permanent and removes all associated data

• get_wallet - Get wallet details by wallet ID. Returns wallet address, chain type, creation/export/import timestamps, policy IDs, and owner information
• list_wallets - List all wallets with pagination. Returns wallet addresses, chain types, and associated metadata
• create_wallet - Create or pregenerate a wallet for a user. Supports Ethereum, Solana, Bitcoin, and all EVM-compatible chains
• get_wallet_balance - Get the current balance of a wallet
• get_wallet_transactions - Get transaction history for a wallet with pagination support
• update_wallet - Update wallet metadata and configuration

Once configured with Claude Desktop, you can ask:

• "List all users in my Privy application"
• "Get user details for DID did:privy:xxx"
• "Search for users with email user@example.com"
• "Find users by wallet address 0x123..."
• "Search for users matching 'john' with phone number +1234567890"
• "Create a new user with email user@example.com"
• "Create a wallet for user did:privy:xxx on Solana"
• "Show me all wallets in the system"
• "Get transaction history for wallet xyz"
• "What's the balance of wallet xyz?"
• "Update wallet metadata for wallet xyz"

Privy.io enforces rate limits:

• User data endpoints: 500 requests per 10 seconds
• Contact Privy support for rate limit increases

This server uses HTTP Basic Authentication with custom headers:

• Authorization: Basic <base64(app_id:app_secret)>
• privy-app-id: <app_id>

All requests are made over HTTPS to https://api.privy.io/v1.

• Ethereum and all EVM-compatible chains
• Solana
• Bitcoin
• Base, Polygon, Arbitrum, Optimism, and more

Users can link accounts from 15+ providers:

• Apple
• Discord
• Farcaster
• GitHub
• Google
• LinkedIn
• Spotify
• Telegram
• TikTok
• Twitter
• And more

pip install -e ".[dev]"
pytest

privy-mcp-server/
├── src/
│   └── privy_mcp/
│       ├── __init__.py      # Package initialization
│       ├── client.py        # Privy API client
│       └── server.py        # MCP server implementation
├── pyproject.toml           # Project dependencies
├── .env.example             # Environment template
└── README.md                # Documentation

• Never commit .env file or expose API credentials
• Store credentials securely using environment variables or secrets management
• API credentials have full access to your Privy application
• This is a defensive security tool - do not use for malicious purposes
• Review Privy's security documentation: docs.privy.io/security

• Verify PRIVY_APP_ID and PRIVY_APP_SECRET are correct
• Check credentials at Dashboard → App Settings → Basics
• Ensure environment variables are loaded

• Reduce request frequency
• Implement exponential backoff
• Contact Privy support for limit increases

• Verify internet connectivity
• Check Privy API status
• Ensure firewall allows HTTPS requests

• Privy.io Documentation
• Privy API Reference
• MCP Specification
• Privy Dashboard

MIT License - See LICENSE file for details

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

• Server Issues: GitHub Issues
• Privy Support: hi@privy.io
• MCP Specification: Model Context Protocol
• Documentation: docs.privy.io

This is an unofficial MCP server implementation. Privy.io has identified MCP as an emerging technology and encourages collaboration. For production use cases, review Privy's official guidance and contact their team at hi@privy.io.

Built on:

• Privy.io - Web3 wallet infrastructure
• Model Context Protocol - Anthropic's MCP specification
• HTTPX - Modern HTTP client for Python