Installation Guide

This guide will help you install MCP Wallet on your system.

System Requirements

Minimum Requirements

Operating System:

macOS 10.15 (Catalina) or later
Windows 10 (1809) or later
Linux (Ubuntu 20.04, Fedora 32, or equivalent)

Hardware:

2 GB RAM
500 MB available disk space
Internet connection

Software:

No additional software required (all dependencies bundled)

Recommended Requirements

4 GB RAM
1 GB available disk space
Stable internet connection

Installation

macOS

Option 1: Download from GitHub Releases (Recommended)

Download the DMG file
- Visit MCP Wallet Releases
- Download MCP-Wallet-{version}.dmg
Open the DMG file
- Double-click the downloaded DMG
- Drag "MCP Wallet" to Applications folder
Open MCP Wallet
- Go to Applications
- Double-click "MCP Wallet"
- If you see "MCP Wallet is from an unidentified developer":
  - Right-click the app
  - Click "Open"
  - Click "Open" again in the dialog
Verify Installation
- MCP Wallet should launch
- You'll see the welcome screen

Option 2: Build from Source

See Building from Source for instructions.

Windows

Option 1: Download from GitHub Releases (Recommended)

Download the installer
- Visit MCP Wallet Releases
- Download MCP-Wallet-{version}.msi or MCP-Wallet-{version}.exe
Run the installer
- Double-click the downloaded file
- If Windows Defender SmartScreen appears:
  - Click "More info"
  - Click "Run anyway"
- Follow the installation wizard
- Choose installation location (default: C:\Program Files\MCP Wallet)
Launch MCP Wallet
- Start Menu → MCP Wallet
- Or desktop shortcut (if created)
Verify Installation
- MCP Wallet should launch
- You'll see the welcome screen

Option 2: Build from Source

See Building from Source for instructions.

Linux

Option 1: Download AppImage (Recommended)

Download AppImage
- Visit MCP Wallet Releases
- Download MCP-Wallet-{version}.AppImage
Make executable
bash
```
chmod +x MCP-Wallet-{version}.AppImage
```
Run MCP Wallet
bash
```
./MCP-Wallet-{version}.AppImage
```
(Optional) Install AppImageLauncher
- Integrates AppImages with system menu
- Download AppImageLauncher

Option 2: Debian/Ubuntu (.deb)

Download .deb package

bash

wget https://github.com/TeamTaoist/MCPWallet-releases/releases/download/v{version}/mcp-wallet_{version}_amd64.deb

Install with apt

bash

sudo apt install ./mcp-wallet_{version}_amd64.deb

Launch MCP Wallet
bash
```
mcp-wallet
```
Or: Applications → MCP Wallet

Option 3: Fedora/RHEL (.rpm)

Download .rpm package

bash

wget https://github.com/TeamTaoist/MCPWallet-releases/releases/download/v{version}/mcp-wallet-{version}.x86_64.rpm

Install with dnf

bash

sudo dnf install ./mcp-wallet-{version}.x86_64.rpm

Launch MCP Wallet
bash
```
mcp-wallet
```
Or: Applications → MCP Wallet

Option 4: Build from Source

See Building from Source for instructions.

Platform-Specific Installation Issues

macOS Issues

"MCP Wallet" is damaged and can't be opened

This happens when macOS Gatekeeper blocks the app.

Solution:

bash

# Remove quarantine attribute
xattr -d com.apple.quarantine /Applications/MCP\ Wallet.app

# Or allow from anywhere (less secure)
sudo spctl --master-disable

App won't open (crashes immediately)

Check Rosetta 2 (Apple Silicon Macs):

bash

# Install Rosetta 2 if not already installed
softwareupdate --install-rosetta

Permission denied errors

Grant necessary permissions:

System Preferences → Security & Privacy
Grant "Full Disk Access" to MCP Wallet (if prompted)

Windows Issues

Windows Defender blocks installation

Solution:

Click "More info" in SmartScreen warning
Click "Run anyway"

Or add exception:

Windows Security → Virus & threat protection
Manage settings → Exclusions
Add an exclusion → File
Select MCP Wallet installer

Missing DLL errors

Install Visual C++ Redistributable:

Download from Microsoft
Install both x64 and x86 versions
Restart computer

WebView2 not found

Install WebView2:

Download from Microsoft
Install and restart

Linux Issues

AppImage won't run

Install FUSE:

bash

# Ubuntu/Debian
sudo apt install fuse libfuse2

# Fedora
sudo dnf install fuse fuse-libs

# Arch
sudo pacman -S fuse2

Missing library errors

Install required libraries:

bash

# Ubuntu/Debian
sudo apt install libwebkit2gtk-4.0-37 libgtk-3-0

# Fedora
sudo dnf install webkit2gtk3 gtk3

# Arch
sudo pacman -S webkit2gtk gtk3

Permission issues

Grant execution permission:

bash

chmod +x MCP-Wallet-{version}.AppImage

Verifying Installation

Check Version

After installation, verify the version:

Open MCP Wallet
Go to Settings → About
Check version number matches download

Check MCP Server

The MCP server should start automatically:

Go to Settings → MCP Server
Status should show "Running"
Default port: 8580

If not running:

Click "Start Server"
Check firewall isn't blocking port 8580

Updating MCP Wallet

Check for Updates

MCP Wallet doesn't auto-update (yet). Check manually:

Visit MCP Wallet Releases
Compare latest version with your version (Settings → About)
Download and install new version if available

Update Process

macOS:

Download new DMG
Drag to Applications (replace existing)
Open updated app

Windows:

Download new installer
Run installer (will upgrade existing installation)
Launch updated app

Linux:

Download new AppImage/package
Replace old file or install new package
Launch updated app

Data Preservation

Your wallet data is stored separately and preserved across updates. No need to backup before updating.

Uninstalling MCP Wallet

Before Uninstalling

Backup Seed Phrase

Make sure you have your 12-word seed phrase backed up before uninstalling!

macOS

Move app to Trash
- Drag "MCP Wallet" from Applications to Trash

Delete app data (optional)

bash

rm -rf ~/Library/Application\ Support/com.mcp-wallet.app
rm -rf ~/Library/Caches/com.mcp-wallet.app
rm -rf ~/Library/Logs/mcp-wallet

Windows

Uninstall via Control Panel
- Settings → Apps → MCP Wallet → Uninstall

Delete app data (optional)

cmd

del /s /q %APPDATA%\com.mcp-wallet.app
del /s /q %LOCALAPPDATA%\com.mcp-wallet.app

Linux

AppImage:

bash

rm MCP-Wallet-{version}.AppImage
rm -rf ~/.config/com.mcp-wallet.app

Debian/Ubuntu:

bash

sudo apt remove mcp-wallet
rm -rf ~/.config/com.mcp-wallet.app

Fedora/RHEL:

bash

sudo dnf remove mcp-wallet
rm -rf ~/.config/com.mcp-wallet.app

Data Locations

Your wallet data is stored locally:

macOS

Application Data:
~/Library/Application Support/com.mcp-wallet.app/

Database:
~/Library/Application Support/com.mcp-wallet.app/wallet.db

Logs:
~/Library/Logs/mcp-wallet/

Cache:
~/Library/Caches/com.mcp-wallet.app/

Windows

Application Data:
%APPDATA%\com.mcp-wallet.app\

Database:
%APPDATA%\com.mcp-wallet.app\wallet.db

Logs:
%APPDATA%\com.mcp-wallet.app\logs\

Cache:
%LOCALAPPDATA%\com.mcp-wallet.app\Cache\

Linux

Application Data:
~/.config/com.mcp-wallet.app/

Database:
~/.config/com.mcp-wallet.app/wallet.db

Logs:
~/.local/share/mcp-wallet/logs/

Cache:
~/.cache/com.mcp-wallet.app/

Firewall Configuration

MCP Wallet needs network access:

Outbound Connections

BSC RPC: https://bsc-dataseed.binance.org
BSC Testnet RPC: https://data-seed-prebsc-1-s1.binance.org:8545
OAuth Server: https://mcp-wallet-oauth.dev-taoist.workers.dev

Inbound Connections (Optional)

MCP Server: localhost:8580 (for AI integration)

Firewall Rules

macOS:

System Preferences → Security & Privacy → Firewall
Allow MCP Wallet to accept incoming connections

Windows:

Windows Defender Firewall → Allow an app
Add MCP Wallet
Allow both Private and Public networks

Linux:

bash

# ufw
sudo ufw allow 8580/tcp

# firewalld
sudo firewall-cmd --add-port=8580/tcp --permanent
sudo firewall-cmd --reload

Next Steps

After installation:

Create Your First Wallet - Set up a new wallet or import existing
Configure Security - Set password and backup seed phrase
Integrate with Claude Code - Connect AI assistant
Learn About Transactions - Understand how transactions work

Need Help?

Having installation issues?

📖 Troubleshooting Guide
📢 Telegram Community - Community discussion and support
🐛 GitHub Issues - Bug reports and feature requests

Successfully installed? Continue to Getting Started →

Installation Guide ​

System Requirements ​

Minimum Requirements ​

Recommended Requirements ​

Installation ​

macOS ​

Option 1: Download from GitHub Releases (Recommended) ​

Option 2: Build from Source ​

Windows ​

Option 1: Download from GitHub Releases (Recommended) ​

Option 2: Build from Source ​

Linux ​

Option 1: Download AppImage (Recommended) ​

Option 2: Debian/Ubuntu (.deb) ​

Option 3: Fedora/RHEL (.rpm) ​

Option 4: Build from Source ​

Platform-Specific Installation Issues ​

macOS Issues ​

"MCP Wallet" is damaged and can't be opened ​

App won't open (crashes immediately) ​

Permission denied errors ​

Windows Issues ​

Windows Defender blocks installation ​

Missing DLL errors ​

WebView2 not found ​

Linux Issues ​

AppImage won't run ​

Missing library errors ​

Permission issues ​

Verifying Installation ​

Check Version ​

Check MCP Server ​

Updating MCP Wallet ​

Check for Updates ​

Update Process ​

Uninstalling MCP Wallet ​

Before Uninstalling ​

macOS ​

Windows ​

Linux ​

Data Locations ​

macOS ​

Windows ​

Linux ​

Firewall Configuration ​

Outbound Connections ​

Inbound Connections (Optional) ​

Firewall Rules ​

Next Steps ​

Need Help? ​

Installation Guide

System Requirements

Minimum Requirements

Recommended Requirements

Installation

macOS

Option 1: Download from GitHub Releases (Recommended)

Option 2: Build from Source

Windows

Option 1: Download from GitHub Releases (Recommended)

Option 2: Build from Source

Linux

Option 1: Download AppImage (Recommended)

Option 2: Debian/Ubuntu (.deb)

Option 3: Fedora/RHEL (.rpm)

Option 4: Build from Source

Platform-Specific Installation Issues

macOS Issues

"MCP Wallet" is damaged and can't be opened

App won't open (crashes immediately)

Permission denied errors

Windows Issues

Windows Defender blocks installation

Missing DLL errors

WebView2 not found

Linux Issues

AppImage won't run

Missing library errors

Permission issues

Verifying Installation

Check Version

Check MCP Server

Updating MCP Wallet

Check for Updates

Update Process

Uninstalling MCP Wallet

Before Uninstalling

macOS

Windows

Linux

Data Locations

macOS

Windows

Linux

Firewall Configuration

Outbound Connections

Inbound Connections (Optional)

Firewall Rules

Next Steps

Need Help?