Add one JSON block to your MCP client config. That's it.

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Then tell your agent: "Create a BotWallet for yourself."

It runs botwallet_register, generates a cryptographic key share locally, and comes back with a deposit address. No setup, no API keys to configure beforehand.

From there:

"Send $5 to @acme-bot for the data report"

If the amount is within guard rails, the agent signs and submits. If not, it asks the human owner for approval.

"Create an invoice for $25 for the consulting session"

The agent creates a paylink. When someone pays it, the USDC goes straight to the wallet.

"Find a speech-to-text API and use it"

The agent searches the x402 catalog, finds a paid API, pays for access, and returns the result.

How signing works

Every wallet uses FROST 2-of-2 threshold signatures. During wallet creation, a key generation ceremony produces two shares:

• S1 — the agent's share, stored locally at ~/.botwallet/seeds/
• S2 — the server's share, held by BotWallet

The full private key never exists. Every transaction requires both parties to co-sign. Neither the agent nor BotWallet can move funds alone. Human owners set spending limits and approve anything outside the rules.

Installation

Claude Desktop

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Cursor

Go to Settings > MCP, click Add new MCP server, and add:

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Cline

Open the Cline sidebar, click MCP Servers, then Configure, and add:

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Other MCP clients

The config is the same everywhere — npx -y @botwallet/mcp as the command.

Global install (alternative)

npm install -g @botwallet/mcp

If you install globally, use botwallet-mcp as the command instead of npx -y @botwallet/mcp.

Environment variables

All optional. The server reads ~/.botwallet/config.json (shared with the CLI) and figures out the rest.

Tools

36 tools across 8 groups.

Wallet management

Payments

Earning

Funding

Withdrawals

x402 paid APIs

History and guard rails

Wallet transfer

Resources

Architecture

┌─────────────────┐     stdio (JSON-RPC)     ┌──────────────────┐
│   AI Client     │◄────────────────────────►│  BotWallet MCP   │
│ (Claude/Cursor) │                          │     Server       │
└─────────────────┘                          └────────┬─────────┘
                                                      │
                                              ┌───────┴───────┐
                                              │               │
                                     ~/.botwallet/     api.botwallet.co
                                     (seeds, config)        (API)
                                                              │
                                                        ┌─────┴─────┐
                                                        │  Solana   │
                                                        │ (mainnet) │
                                                        └───────────┘

The server runs locally on the agent's machine. Key shares stay in ~/.botwallet/seeds/ and are never sent over the network. The server talks to the BotWallet API for co-signing and submits the combined signature to Solana.

Security

The agent can't bypass spending limits. Those are enforced server-side. Transactions above the auto-approve threshold go to the human owner for approval. Key shares are stored locally and never leave the machine. There is no full private key anywhere in the system.

See SECURITY.md for vulnerability reporting.

CLI interop

This MCP server and the BotWallet CLI share the same local files:

• Config: ~/.botwallet/config.json
• Seeds: ~/.botwallet/seeds/*.seed
• Export format: .bwlt (encrypted, works both directions)

A wallet created with the CLI works in the MCP server, and vice versa.

Development

git clone https://github.com/botwallet-co/mcp.git
cd mcp
npm install
npm run build
npm test                # 76 tests (unit + integration + E2E)
npm run inspect         # Open in MCP Inspector

License

Apache 2.0