MCP Wallet

A secure crypto wallet with AI agent integration via OAuth 2.1. Enable AI assistants like Claude Code to manage your crypto assets with your approval.

🌟 What is MCP Wallet?

MCP Wallet is a desktop crypto wallet that lets AI assistants help you manage your crypto assets safely. Your AI assistant can:

Check your balance
Send transactions
Track transaction status

You stay in control - approve AI access once during OAuth authorization, then revoke anytime in Settings.

🚀 Quick Start for Users

1. Download & Install

Download the latest release for your platform:

Download: MCP Wallet Releases
macOS: MCP-Wallet.dmg
Windows: MCP-Wallet.msi or MCP-Wallet.exe
Linux: MCP-Wallet.AppImage

Or build from source (see Developer Guide below).

2. Set Up Your Wallet

Launch MCP Wallet
Create or Import Wallet
- Create new: Get a 12-word seed phrase (save it safely!)
- Import existing: Enter your seed phrase
Enable API Access
- Go to Settings → Accounts
- Enable API for the account you want AI to use

3. Connect Your AI Assistant

MCP Wallet currently supports:

Direct Integration (HTTP):

✅ Claude Code - Setup Guide
✅ Gemini CLI - Setup Guide

SSE Adapter Required (Old MCP Spec):

✅ Trae - Requires SSE Adapter v2.0

Coming Soon:

🔜 Cursor - Direct integration
🔜 GitHub Copilot - Direct integration

📖 User Guide

Claude Code Integration

Step 1: Start MCP Server

Open MCP Wallet
Unlock your wallet
The MCP server starts automatically on port 8580

Step 2: Add to Claude Code

claude mcp add --transport http mcp-wallet http://localhost:8580/mcp

This command adds MCP Wallet to your Claude Code configuration automatically.

Step 3: Authorize Claude Code

In Claude Code, run /mcp command
Claude will open your browser to authorize
Click "Auth" button on the page
MCP Wallet will show authorization dialog
Review the permissions and click "Approve"
Go back to browser and click "Redirect"
Done! Claude Code can now access your wallet

Step 4: Try It Out

Ask Claude Code:

"How much BNB do I have?"
"Send 0.01 BNB to 0x..."
"What's my wallet address?"

Gemini CLI Integration

Step 1: Install Gemini CLI

If you haven't installed Gemini CLI yet:

npm install -g @google/gemini-cli

Or with yarn:

yarn global add @google/gemini-cli

Step 2: Start MCP Server

Open MCP Wallet
Unlock your wallet
The MCP server starts automatically on port 8580

Step 3: Add MCP Wallet to Gemini CLI

Run this single command to add MCP Wallet:

gemini mcp add --transport http mcp-wallet http://localhost:8580/mcp

This will add MCP Wallet to your Gemini CLI configuration.

Step 4: Authorize Gemini CLI

When Gemini CLI first uses MCP Wallet, it will trigger OAuth authorization
MCP Wallet will show authorization dialog
Review the permissions:
- Client: gemini-cli
- Permissions: wallet:read wallet:write
Click "Approve" to grant access
Done! Gemini CLI can now access your wallet

Step 5: Try It Out

Ask Gemini:

gemini chat

> What's my wallet address?
> How much BNB do I have in my wallet?
> Check my USDT balance
> Send 0.01 BNB to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Managing Access

You can revoke Gemini CLI's access anytime:

Open MCP Wallet
Go to Settings → Authorized AI Clients
Find "gemini-cli" and click "Revoke All"

Codebuddy Integration

Step 1: Install Codebuddy CLI

If you haven't installed Codebudd CLI yet:

npm install -g @tencent-ai/codebuddy-code

Or with yarn:

yarn global add @tencent-ai/codebuddy-code

Step 2: Start MCP Server

Open MCP Wallet
Unlock your wallet
The MCP server starts automatically on port 8580

Step 3: Add MCP Wallet to Codebuddy CLI

Run this single command to add MCP Wallet:

codebuddy mcp add --transport http mcp-wallet http://localhost:8580/mcp

This will add MCP Wallet to your Codebuddy CLI configuration.

Step 4: Authorize Codebuddy CLI

When Codebuddy CLI first uses MCP Wallet, it will trigger OAuth authorization
MCP Wallet will show authorization dialog
Review the permissions:
- Client: codebuddy-cli
- Permissions: wallet:read wallet:write
Click "Approve" to grant access
Done! Codebuddy CLI can now access your wallet

Step 5: Try It Out

Ask Codebuddy:

codebuddy chat

> What's my wallet address?
> How much BNB do I have in my wallet?
> Check my USDT balance
> Send 0.01 BNB to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Managing Access

You can revoke Codebuddy CLI's access anytime:

Open MCP Wallet
Go to Settings → Authorized AI Clients
Find "codebuddy-cli" and click "Revoke All"

Other AI Client align with latest MCP Specicication

{
  "mcpServers": {
    "mcp-wallet": {
      "serverUrl": "http://127.0.0.1:8580/mcp"
    }
  }
}

or

{
  "mcpServers": {
    "mcp-wallet": {
      "url": "http://127.0.0.1:8580/mcp"
    }
  }
}

Trae (SSE Transport)

Note: Trae uses the old MCP specification (2024-11-05) which only supports SSE transport. To use Trae with MCP Wallet, you need to install the SSE Adapter v2.0.

Step 1: Install SSE Adapter

# Clone the SSE Adapter repository
git clone https://github.com/teamtaoist/mcp-wallet-sse-adapter.git
cd mcp-wallet-sse-adapter

# Install dependencies
npm install

# Start the adapter
npm start

The SSE Adapter will:

Listen on port 8581 (default)
Translate SSE ↔ HTTP protocols
Manage OAuth flows for old-spec clients
Enable one-time authorization with session reuse

Step 2: Configure Your AI Client

For Trae (~/.trae/config.json):

{
  "mcpServers": {
    "mcp-wallet": {
      "url": "http://localhost:8581/mcp",
      "transport": "sse",
      "oauth": {
        "authorizationEndpoint": "http://localhost:8581/oauth/authorize",
        "tokenEndpoint": "https://mcp-wallet-oauth.dev-taoist.workers.dev/oauth/token",
        "clientId": "trae",
        "scopes": ["wallet:read", "wallet:write"]
      }
    }
  }
}

For other SSE-only clients:

{
  "mcpServers": {
    "mcp-wallet": {
      "url": "http://localhost:8581/mcp",
      "transport": "sse",
      "oauth": {
        "authorizationEndpoint": "http://localhost:8581/oauth/authorize",
        "tokenEndpoint": "https://mcp-wallet-oauth.dev-taoist.workers.dev/oauth/token",
        "clientId": "your-client-name",
        "scopes": ["wallet:read", "wallet:write"]
      }
    }
  }
}

Step 3: Authorize Your AI Client

When your AI assistant first tries to use MCP Wallet:

SSE Adapter automatically opens your browser
MCP Wallet shows authorization dialog
Review and click "Approve"
Browser shows success page (you can close it)
AI assistant can now access your wallet

Note: With v2.0, you only need to authorize once per client. The adapter uses client fingerprinting to reuse sessions across multiple SSE connections.

Step 4: Try It Out

Ask your AI assistant:

"Check my BNB balance"
"Send 0.01 BNB to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
"What's my wallet address?"

Learn More: See the SSE Adapter documentation for detailed setup instructions.

Security Features

✅ OAuth 2.1 Authentication - Industry-standard secure authorization ✅ One-Time Approval - Approve AI access once, revoke anytime ✅ Encrypted Storage - Private keys encrypted with AES-256-GCM ✅ Testnet Support - Test safely on BSC Testnet first

Network Support

Currently supported:

Binance Smart Chain (BSC)
- Mainnet
- Testnet

Coming soon:

Ethereum
Polygon
More ERC-20 tokens

🛠 For Developers

Prerequisites

Node.js v18 or higher
Rust (latest stable)
System dependencies (varies by platform)

macOS:

xcode-select --install

Linux:

sudo apt update
sudo apt install libwebkit2gtk-4.0-dev build-essential curl wget \
    file libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev

Windows:

Installation

::: warning Not Open Source Yet MCP Wallet is currently closed source but will be open sourced in the future. The installation instructions below are for reference when the repository becomes public. :::

# Clone the repository (when available)
git clone https://github.com/teamtaoist/mcp-wallet.git
cd mcp-wallet

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

Project Structure

mcp-wallet/
├── src/                    # Vue.js frontend
│   ├── components/         # UI components
│   ├── stores/            # Pinia state management
│   └── types/             # TypeScript definitions
├── src-tauri/             # Rust backend
│   └── src/
│       ├── commands/      # Tauri commands
│       ├── wallet/        # Wallet operations
│       ├── blockchain/    # Blockchain integration
│       ├── mcp/          # MCP server
│       ├── oauth/        # OAuth 2.1 implementation
│       └── database/     # SQLite operations
├── docs/                  # Documentation
└── tests/                # Test scripts

MCP Tools API

MCP Wallet provides 4 tools for AI agents:

wallet_get_address - Get the active wallet address
wallet_get_balance - Get token balance (supports BNB, USDT, or all tokens)
wallet_propose_transaction - Send tokens (BNB or USDT)
wallet_get_transaction_status - Check transaction status

OAuth 2.1 Implementation

MCP Wallet implements OAuth 2.1 Authorization Code Flow with PKCE (S256):

Architecture:

MCP Wallet (Authorization Server) - Issues authorization codes
OAuth Server (Token Server) - Exchanges codes for access tokens
AI Client (Claude Code) - Requests access via OAuth

Flow:

AI client redirects to authorization endpoint
User approves in MCP Wallet dialog
Authorization code issued
AI client exchanges code for access token (with PKCE verification)
AI client uses access token for MCP requests

Endpoints:

Authorization: http://localhost:8580/oauth/authorize
Token: https://mcp-wallet-oauth.dev-taoist.workers.dev/oauth/token
Metadata: http://localhost:8580/.well-known/oauth-authorization-server

Testing

# Run OAuth compliance test
./tests/test-token-endpoint.sh

# Run end-to-end OAuth test
./tests/test-e2e-oauth.sh

# Run approval UI test
./tests/test-approval-ui.sh

Creating Releases

MCP Wallet uses GitHub Actions for automated multi-platform releases.

Quick Release:

# Update versions in package.json, Cargo.toml, and tauri.conf.json
# Then create and push a tag
git tag v0.1.0
git push origin v0.1.0

# GitHub Actions will automatically:
# - Build for macOS (Universal), Windows (x64), and Linux (x64)
# - Create a draft release with all artifacts
# - Generate checksums

For detailed release instructions, see .github/RELEASE_GUIDE.md

📚 Documentation

User Guide - [Coming soon - VitePress site]
Developer Docs - [Coming soon - VitePress site]
API Reference - See MCP Tools API above
OAuth Implementation - See docs/ folder

🐛 Bug Reports & Feature Requests

Telegram Community: https://t.me/aipaywallet
Bug Reports: GitHub Issues
Feature Requests: GitHub Issues

🔒 Security

Security Best Practices

Start with Testnet - Always test on BSC Testnet first
Separate Wallet - Use a dedicated wallet for AI access
Regular Backups - Back up your seed phrase
Monitor Transactions - Check transaction history regularly

Reporting Security Issues

If you discover a security vulnerability, please email security@example.com. Do not create a public issue.

⚠️ Disclaimer

This software is provided as-is. Use at your own risk. The authors are not responsible for any loss of funds. Always:

Test on testnet first
Use small amounts
Verify all transactions
Keep your seed phrase secure

🗺️ Roadmap

Current Version (v0.1.0)

✅ BSC support (mainnet & testnet)
✅ BNB & USDT transfers
✅ OAuth 2.1 authentication
✅ Claude Code integration

Next Version (v0.2.0)

Future

Multi-chain support (Polygon, Arbitrum)
DeFi integrations
NFT support
Multi-signature wallets

💬 Community

Telegram: https://t.me/aipaywallet

🙏 Acknowledgments

Built with:

Tauri - Desktop app framework
Vue.js - Frontend framework
ethers.js - Ethereum library
Binance Smart Chain - Blockchain network

Need help? Join our Telegram community or open an issue.

Name		Name	Last commit message	Last commit date
Latest commit History 87 Commits
.github		.github
.vscode		.vscode
docs		docs
public		public
src-tauri		src-tauri
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
project-instructions.md		project-instructions.md
tailwind.config.js		tailwind.config.js
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation