Privy.io MCP Server
Enables linking Apple OAuth accounts to users during user creation.
Allows creating wallets, checking balances, and retrieving transaction history on the Bitcoin blockchain.
Enables linking Discord OAuth accounts to users during user creation.
Allows creating wallets, checking balances, and retrieving transaction history on Ethereum and EVM-compatible chains.
Enables linking Farcaster OAuth accounts to users during user creation.
Enables linking GitHub OAuth accounts to users during user creation.
Enables linking Google OAuth accounts to users during user creation.
Supports wallet creation and transaction history on the Optimism (OP Mainnet) chain.
Supports wallet creation and transaction history on the Polygon chain.
Allows creating wallets, checking balances, and retrieving transaction history on Solana.
Enables linking Spotify OAuth accounts to users during user creation.
Enables linking Telegram OAuth accounts to users during user creation.
Enables linking TikTok OAuth accounts to users during user creation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Privy.io MCP Server check wallet balance for 0x1234abcd"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Privy.io MCP Server
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.
Features
User Management
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
Wallet Management
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
Related MCP server: Celo MCP Server
Installation
Prerequisites
Python 3.10 or higher
Privy.io account with API credentials
Quick Start with uvx (Recommended)
The easiest way to use this MCP server is with uvx, which automatically fetches the package from PyPI:
uvx privy-mcp-serverNo installation needed! Configure your MCP client (see Usage below) and you're ready to go.
Manual Installation (Development)
For local development:
Clone the repository:
git clone https://github.com/incentivai-io/privy-mcp-server.git
cd privy-mcp-serverCreate virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activateInstall dependencies:
pip install -e .Configure environment variables:
cp .env.example .envEdit .env and add your Privy credentials:
PRIVY_APP_ID=your_app_id_here
PRIVY_APP_SECRET=your_app_secret_hereGet your credentials: Dashboard → App Settings → Basics on Privy.io
Usage
Running the Server
Run directly with Python:
python -m privy_mcpOr use the MCP inspector for testing:
npx @modelcontextprotocol/inspector python -m privy_mcpFor example, from the project directory:
npx @modelcontextprotocol/inspector python -m privy_mcpConfiguring with Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Using uvx (Recommended)
{
"mcpServers": {
"privy": {
"command": "uvx",
"args": ["privy-mcp-server"],
"env": {
"PRIVY_APP_ID": "your_app_id_here",
"PRIVY_APP_SECRET": "your_app_secret_here"
}
}
}
}Using local Python installation
{
"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.
Available Tools
User Management
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 metadatalist_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 metadataget_user_by_wallet- Query and retrieve user information by blockchain wallet address. Supports Ethereum, Solana, Bitcoin, and all EVM-compatible chainscreate_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 walletdelete_user- Delete a user by Privy DID. This action is permanent and removes all associated data
Wallet Management
get_wallet- Get wallet details by wallet ID. Returns wallet address, chain type, creation/export/import timestamps, policy IDs, and owner informationlist_wallets- List all wallets with pagination. Returns wallet addresses, chain types, and associated metadatacreate_wallet- Create or pregenerate a wallet for a user. Supports Ethereum, Solana, Bitcoin, and all EVM-compatible chainsget_wallet_balance- Get the current balance of a walletget_wallet_transactions- Get transaction history for a wallet with pagination supportupdate_wallet- Update wallet metadata and configuration
Example Queries
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"
API Rate Limits
Privy.io enforces rate limits:
User data endpoints: 500 requests per 10 seconds
Contact Privy support for rate limit increases
Authentication
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.
Supported Blockchain Chains
Ethereum and all EVM-compatible chains
Solana
Bitcoin
Base, Polygon, Arbitrum, Optimism, and more
OAuth Providers Supported
Users can link accounts from 15+ providers:
Apple
Discord
Farcaster
GitHub
Google
LinkedIn
Spotify
Telegram
TikTok
Twitter
And more
Development
Running Tests
pip install -e ".[dev]"
pytestProject Structure
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 # DocumentationSecurity Considerations
Never commit
.envfile or expose API credentialsStore 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
Troubleshooting
Authentication Errors
Verify
PRIVY_APP_IDandPRIVY_APP_SECRETare correctCheck credentials at Dashboard → App Settings → Basics
Ensure environment variables are loaded
Rate Limit Errors
Reduce request frequency
Implement exponential backoff
Contact Privy support for limit increases
Connection Errors
Verify internet connectivity
Check Privy API status
Ensure firewall allows HTTPS requests
Resources
License
MIT License - See LICENSE file for details
Contributing
Contributions welcome! Please:
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
Support
Server Issues: GitHub Issues
Privy Support: hi@privy.io
MCP Specification: Model Context Protocol
Documentation: docs.privy.io
Disclaimer
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.
Acknowledgments
Built on:
Privy.io - Web3 wallet infrastructure
Model Context Protocol - Anthropic's MCP specification
HTTPX - Modern HTTP client for Python
Available Tools
12 toolscreate_userA
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.
Inputs: linked_accounts (required), create_embedded_wallet. Returns: object
create_walletC
Create or pregenerate a wallet for a user. Supports Ethereum, Solana, Bitcoin, and all EVM-compatible chains.
Inputs: user_id (required), chain_type. Returns: object
delete_userA
Delete a user by Privy DID. This action is permanent and removes all associated data.
Inputs: user_id (required). Returns: object
get_userA
Get user details by Privy DID (decentralized identifier). Returns user data including linked accounts (email, phone, wallet, OAuth providers), MFA methods, creation timestamps, terms acceptance, and custom metadata.
Inputs: user_id (required). Returns: object
get_user_by_walletA
Query and retrieve user information by blockchain wallet address. Supports Ethereum, Solana, Bitcoin, and all EVM-compatible chains.
Inputs: wallet_address (required). Returns: object
get_walletA
Get wallet details by wallet ID. Returns wallet address, chain type, creation/export/import timestamps, policy IDs, and owner information.
Inputs: wallet_id (required). Returns: object
get_wallet_balanceB
Get the current balance of a wallet.
Inputs: wallet_id (required). Returns: object
get_wallet_transactionsB
Get transaction history for a wallet with pagination support.
Inputs: wallet_id (required), limit, cursor. Returns: object
list_usersA
List all users with pagination support. Returns paginated list of users with their linked accounts, wallets, and metadata.
Inputs: limit, cursor. Returns: object
list_walletsB
List all wallets with pagination. Returns wallet addresses, chain types, and associated metadata.
Inputs: limit, cursor. Returns: object
search_usersA
Search for users by search term OR specific identifiers (emails, phone numbers, wallet addresses). Note: Use either search_term OR specific identifiers, not both. Returns user data matching the search criteria including linked accounts, MFA methods, and metadata.
Inputs: search_term, emails, phone_numbers, wallet_addresses. Returns: object
update_walletC
Update wallet metadata and configuration.
Inputs: wallet_id (required), updates (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool has a clearly distinct purpose: user creation vs wallet creation, different retrieval methods (by DID, by wallet address, search), and separate actions for wallets (balance, transactions, update). No overlapping functionality.
All tools follow a consistent verb_noun pattern (create_user, get_wallet_balance, list_users) with occasional prepositions for specificity (get_user_by_wallet). No mixing of conventions or vague verbs.
12 tools cover the main operations for user and wallet management without being excessive. Each tool serves a clear need, and the count is appropriate for the server's scope.
Covers most CRUD operations: create, read, delete for users; create, read, update for wallets. Missing update_user and delete_wallet, but the core workflows are well-supported, and agents can likely work around minor gaps.
Maintenance
Related MCP Connectors
EVM wallet reads, simulation, and transaction execution under user-defined authorization policies.
Provide AI agents and automation tools with contextual access to blockchain data including balance…
Verified EVM, Aptos and finance tools for AI agents; gas for 14 chains. Pay per call (x402).
Agent-complete, permission-scoped product operations for Priorify workspaces.
Related MCP Servers
AlicenseBqualityDmaintenanceEnables AI agents to create wallets, sign transactions, and manage blockchain operations across multiple chains like Ethereum, Solana, and more via Privy.242MIT
Celo MCP Serverofficial
AlicenseBqualityBmaintenanceProvides comprehensive access to Celo blockchain data, token operations, NFT management, smart contract interactions, transaction handling, governance, and staking operations.17232 PyPI5MIT
onchainos MCP Serverofficial
AlicenseNot gradedqualityBmaintenanceEnables on-chain operations including token search, market data, wallet management, swap execution, and DApp interactions across 20+ blockchains.346MIT- FlicenseNot gradedqualityDmaintenanceEnables read and write access to the Celo blockchain including balance checks, token transfers, swaps, agent identity (ERC-8004), and x402 micropayments, returning unsigned transactions for user signing.-