Gemini CLI Integration

Integrate MCP Wallet with Gemini CLI to enable AI-powered wallet management with Google's advanced AI assistant.

Overview

Gemini CLI is Google's AI assistant for developers that supports MCP integration. This guide shows you how to connect MCP Wallet to Gemini CLI using HTTP transport and OAuth 2.1 authentication.

Features:

• ✅ HTTP Transport (Direct integration, no adapter needed)
• ✅ OAuth 2.1 authentication with PKCE
• ✅ Balance checking
• ✅ Transaction sending
• ✅ Transaction monitoring
• ✅ Multi-token support

Prerequisites

Before you begin, ensure you have:

1. MCP Wallet installed and running

   • Download: MCP Wallet Releases
   • Installation Guide

2. Wallet created and unlocked

   • Getting Started Guide

3. Node.js v18 or higher

   • Required for Gemini CLI
   • Download: Node.js

4. API access enabled

   • Settings → Accounts → Enable API toggle

Step-by-Step Setup

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

TIP

Verify installation with:

gemini --version

Step 2: Start MCP Wallet

1. Launch MCP Wallet application
2. Unlock your wallet with your password
3. The MCP server starts automatically on port 8580

TIP

You can verify the MCP server is running by checking Settings → MCP Server. You should see "API Endpoint: http://localhost:8580/mcp".

Step 3: Enable API Access

1. Go to Settings → Accounts
2. Find the account you want AI to use
3. Toggle "Enable API" to ON

Recommended

Create a dedicated account for AI access and keep limited funds in it for better security.

Step 4: Add MCP Wallet to Gemini CLI

Use this single command to add MCP Wallet:

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

This command:

• Adds MCP Wallet to your Gemini CLI configuration
• Sets up HTTP transport to connect to the MCP server
• Configures the connection to http://localhost:8580/mcp

TIP

The configuration is saved to ~/.gemini/config.json (macOS/Linux) or %APPDATA%\.gemini\config.json (Windows).

Step 5: Authorize Gemini CLI

Now let's connect Gemini CLI to your wallet:

1. Start Gemini CLI

   gemini chat

2. When Gemini first uses MCP Wallet tools, it will trigger OAuth authorization

3. MCP Wallet will show authorization dialog

   The dialog displays:

   • Client name: "gemini-cli"
   • Requested permissions: wallet:read wallet:write
   • Your account address

4. Review and click "Approve"

5. Done! Gemini CLI now has access to your wallet

Troubleshooting

If the authorization dialog doesn't appear:

• Make sure MCP Wallet is running and unlocked
• Check that API access is enabled for at least one account
• Verify the MCP server is running in Settings → MCP Server

Step 6: Test the Connection

Try these commands in Gemini CLI to test your connection:

gemini chat

Check your wallet address:

> What's my wallet address?

Check your balance:

> How much BNB do I have in my wallet?

Check token balance:

> Check my USDT balance

Send a test transaction (testnet recommended):

> Send 0.001 BNB to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Available Commands

Here's what you can ask Gemini CLI to do:

Balance Queries

How much BNB do I have?
What's my USDT balance?
Show me all my token balances
Check my wallet balance

Address Information

What's my wallet address?
Show my wallet address
Get my wallet address

Transactions

Send 0.01 BNB to 0x742d35...
Transfer 10 USDT to 0x8388af...
Send 0.001 BNB to this address

Transaction Status

What's the status of transaction 0x4952c33d...?
Check transaction 0x4952c33d...
Get transaction status for 0x4952c33d...

Security Features

OAuth 2.1 Authentication

MCP Wallet uses industry-standard OAuth 2.1 with PKCE for security:

• Authorization Code Flow - Secure token exchange
• PKCE (S256) - Prevents authorization code interception
• Short-lived tokens - Access tokens expire after 1 hour
• Refresh tokens - Valid for 30 days

One-Time Approval

After completing OAuth authorization, Gemini CLI can execute transactions:

• Initial authorization - You approve once during OAuth flow
• Automatic execution - Transactions executed without further approval
• Transaction history - All AI transactions are logged and labeled as "AI-initiated"
• Revoke access - Disable API access anytime in Settings to stop all AI transactions

Coming Soon: Spending Limits

Per-transaction and daily spending limits will be added in a future update for additional control over AI transactions.

Managing Access

You can revoke Gemini CLI's access anytime:

1. Open MCP Wallet
2. Go to Settings → Authorized AI Clients
3. Find "gemini-cli" in the list
4. Click "Revoke All" to remove all active sessions

This will immediately invalidate all tokens and prevent further access.

Troubleshooting

Authorization Dialog Not Appearing

Problem: Authorization dialog doesn't show when Gemini tries to use wallet

Solutions:

1. Make sure MCP Wallet is running and unlocked
2. Check API is enabled: Settings → Accounts → Enable API
3. Verify MCP server is running: Settings → MCP Server

"Connection Failed" Error

Problem: Gemini CLI shows connection error

Solutions:

1. Verify MCP server is running on port 8580
2. Check firewall isn't blocking localhost:8580
3. Restart MCP Wallet
4. Re-add the MCP server configuration:

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

Transaction Failed

Problem: Transaction rejected or failed

Solutions:

1. Insufficient funds - Make sure you have enough balance + gas fees
2. Network issues - Check your internet connection
3. Wrong network - Verify you're on the correct network (testnet vs mainnet)
4. API disabled - Check that API access is still enabled

Unauthorized Error

Problem: "401 Unauthorized" or "Invalid token"

Solutions:

1. Re-authorize - Use Gemini CLI again and approve in wallet
2. Check token expiry - Access tokens expire after 1 hour
3. Check wallet lock - Unlock your wallet if it's locked
4. Restart Gemini CLI - Sometimes helps refresh the connection

Best Practices

Testing

1. Start with testnet - Use BSC Testnet before mainnet
2. Small amounts - Test with tiny amounts first
3. Verify transactions - Always check transaction hashes on block explorer

Security

1. Separate account - Use a dedicated account for AI access
2. Limited funds - Keep only needed amount in AI-accessible account
3. Regular monitoring - Check transaction history regularly
4. Revoke when not in use - Disable API access when you don't need it

Network Configuration

BSC Testnet (for testing):

• Network: BSC Testnet
• Chain ID: 97
• Get testnet BNB: BSC Faucet

BSC Mainnet (for production):

• Network: BSC Mainnet
• Chain ID: 56
• Real BNB required

Production Warning

When using mainnet:

• Double-check addresses - Transactions are irreversible
• Start with small amounts - Test first!
• Monitor closely - Check all AI-initiated transactions

Advanced Configuration

Custom Port

If port 8580 conflicts with another service:

1. Go to Settings → MCP Server
2. Change port (e.g., to 8581)
3. Update Gemini CLI config:

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

Multiple Accounts

To use multiple accounts with Gemini CLI:

1. Set up first account as described above
2. To switch accounts:
   • Go to Settings → AI Agent Account
   • Select different account
   • Gemini CLI will use the new account automatically

Example Usage Session

Here's a complete example session with Gemini CLI:

$ gemini chat

> What's my wallet address?
Your wallet address is: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

> How much BNB do I have?
You have 0.892 BNB in your wallet.

> What about USDT?
You have 50.00 USDT in your wallet.

> Send 0.01 BNB to 0x8388af6d7e5c8e5c5e5c5e5c5e5c5e5c5e5c5e5c
Sending 0.01 BNB to 0x8388af6d7e5c8e5c5e5c5e5c5e5c5e5c5e5c5e5c...
Transaction sent successfully!
Transaction hash: 0x4952c33d1689cd57090d537052a1bc2efbc206cd65e36be048f04e4840cc75b7

> What's the status of that transaction?
Transaction 0x4952c33d... is confirmed and successful.

Next Steps

Now that you're connected:

• 📖 Learn about Security Best Practices
• 💰 Learn about Managing Transactions
• 🆘 Get help in Troubleshooting Guide

Need Help?

• 📢 Telegram Community - Community discussion and support
• 🐛 GitHub Issues - Bug reports and feature requests
• 📖 FAQ