Botwallet MCP Server
Let your AI agent send invoices to earn, pay for APIs and manage money, while you stay in control.
接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令? 两种安装方式的区别
Give your AI agent financial autonomy without giving up control. Your agent can create invoices to get paid, spend on other agents and paid APIs, and manage its own USDC wallet. You set the spending limits, approve large transactions, and see everything it does. Works with Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and any MCP-compatible client.
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.
Every wallet uses FROST 2-of-2 threshold signatures. During wallet creation, a key generation ceremony produces two shares:
~/.botwallet/seeds/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.
Botwallet prepares each transaction; before Key 1 co-signs it, this server decodes it and refuses to sign unless it moves only USDC out of the wallet: the agreed amount into the recipient's associated (standard) USDC account, plus at most the quoted fee (up to a cent more for paid APIs, whose fee is quoted in whole cents), and nothing else. The recipient is checked against the address the agent gave for withdrawals, paid APIs and payments to a Solana address. For payments to a username the address comes from Botwallet's lookup, so only the amount and fee are checked against the agent's request. The Agent CLI and the signing page apply the same rules.
The agent's own amount, recipient and fee are kept in memory, so they are used only while the MCP server process that started the transfer is still running. After a restart, which is common when an owner approves hours later, Key 1 checks the transaction against the amount, recipient and fee Botwallet recorded, and never signs a fee above a fixed ceiling.
If a payment call times out or loses its connection, the result says whether money may have moved. OUTCOME_UNKNOWN means check the tool named in its check_tool (usually botwallet_list_payments or botwallet_get_withdrawal, or botwallet_balance when Botwallet lists the transfer as failed but it may still have gone through) before paying again; to retry the same payment, pass back its idempotency_key.
Sent, not confirmed yet. Botwallet waits for Solana to confirm a payment or withdrawal. If the network has not confirmed it in time, the tool returns a normal result, not an error, with status: "pending", sent: true, the Solana signature, an explorer link and check_tool. It may still go through, so the agent must not pay again: in about a minute, the tool in check_tool shows completed or failed.
Frozen wallet. The owner can freeze the wallet in the Botwallet dashboard. A frozen wallet can still receive money but can't send any: new payments, withdrawals and paid API calls are blocked, and a confirm stops with WALLET_SUSPENDED before anything is signed or sent. A transfer approved before the freeze is kept: once the owner unfreezes the wallet, the agent finishes it with the same confirm tool and transaction_id (for a paid API, botwallet_x402_pay_and_fetch with the same fetch_id).
Retrying a request. botwallet_pay and botwallet_withdraw return an idempotency_key. Calling the tool again with that key returns what became of the first request instead of making a second one. Without one, a new key is made, so the call is a new payment. A key already used for another kind of request, or for one that is still being created, returns IDEMPOTENCY_KEY_CONFLICT.
Add to your Claude Desktop config file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json{
"mcpServers": {
"botwallet": {
"command": "npx",
"args": ["-y", "@botwallet/mcp"]
}
}
}
claude mcp add botwallet -- npx -y @botwallet/mcp
This adds it to the current project. To use it in every project, add --scope user:
claude mcp add --scope user botwallet -- npx -y @botwallet/mcp
On native Windows (not WSL), npx needs a cmd /c wrapper: claude mcp add botwallet -- cmd /c npx -y @botwallet/mcp.
Go to Settings > MCP, click Add new MCP server, and add:
{
"mcpServers": {
"botwallet": {
"command": "npx",
"args": ["-y", "@botwallet/mcp"]
}
}
}
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"botwallet": {
"command": "npx",
"args": ["-y", "@botwallet/mcp"]
}
}
}
Open the Cline sidebar, click MCP Servers, then Configure, and add:
{
"mcpServers": {
"botwallet": {
"command": "npx",
"args": ["-y", "@botwallet/mcp"]
}
}
}
The config is the same everywhere — npx -y @botwallet/mcp as the command.
npm install -g @botwallet/mcp
If you install globally, use botwallet-mcp as the command instead of npx -y @botwallet/mcp.
All optional. The server reads ~/.botwallet/config.json (shared with the CLI) and figures out the rest. Without these variables it uses the default wallet; registering or importing a wallet makes it the default.
36 tools across 8 groups.
┌─────────────────┐ 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 are stored in ~/.botwallet/seeds/ and are never sent to Botwallet. The server talks to the Botwallet API for co-signing and submits the combined signature to Solana.
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. There is no full private key anywhere in the system.
Every tool carries MCP tool annotations. Balance, history and lookups are marked read-only, so clients that support annotations can run them without asking. Tools that move money (botwallet_pay, botwallet_withdraw, the confirm tools, botwallet_x402_pay_and_fetch), touch Key 1 (botwallet_wallet_backup, botwallet_wallet_export, botwallet_wallet_import) or change the owner are marked destructive, so clients can keep asking before those. Allowing the read-only tools is safer than "always allow" for the whole server.
Key 1 (the agent's key share) is stored only on the agent's machine and is never sent to Botwallet. Registering saves the API key to ~/.botwallet/config.json without showing it. Two things do reveal key material, so use them only when the owner asks:
botwallet_wallet_backup shows Key 1 (12 words) to the agent so it can pass them to the owner, who needs them to withdraw and to recover the wallet. The words then sit in the AI conversation, so treat that conversation as sensitive. As in the CLI, it takes two calls: the first returns a one-time code, valid for 30 seconds, and the second, with that code, reveals the words. This guards against revealing Key 1 by accident; it does not stop an agent that is set on revealing it.botwallet_wallet_export writes a .bwlt file with Key 1 and the API key. Anyone holding the file can import the wallet within 24 hours.See SECURITY.md for vulnerability reporting.
This MCP server and the Botwallet CLI share the same local files:
~/.botwallet/config.json~/.botwallet/seeds/*.seed.bwlt (encrypted, works both directions; holds Key 1 and the API key, so keep it private)A wallet created with the CLI works in the MCP server, and vice versa.
git clone https://github.com/botwallet-co/mcp.git
cd mcp
npm install
npm run build
npm test # unit + integration tests, offline
npm run test:e2e # E2E tests against the live API (no payments)
npm run inspect # Open in MCP Inspector
MCP server for Botwallet — Give any AI agent a wallet via Model Context Protocol. FROST threshold signing, x402 paid APIs, spending guard rails.
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式,而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
Botwallet Co 通过 stdio 在本地运行。
上次检查时间:2026-10-28。 MCP server for Botwallet — Give any AI agent a wallet via Model Context Protocol. FROST threshold signing, x402 paid APIs, spending guard rails.