b-open-io 1Sat Wallet Desktop — MCP Server
The 1Sat desktop wallet exposes an MCP server on 127.0.0.1:3322 when running. It provides 28 tools for browser automation, main-wallet WebView control, blockchain data queries, wallet operations, and log inspection. Authentication is handled automatically by 1sat mcp-proxy.
Zero-Config Setup (Plugin Users)
If the 1sat Claude Code plugin is installed, the .mcp.json is already configured. No manual steps — install the CLI, launch the wallet, MCP tools appear automatically.
Getting Started
Install the 1Sat CLI globally:
bun install -g @1sat/cliLaunch the 1Sat wallet desktop app. The MCP server starts on
127.0.0.1:3322automatically.MCP tools appear in Claude Code. The 1sat plugin ships
.mcp.json. Restart Claude Code to pick it up.Verify the server is reachable:
curl -s http://127.0.0.1:3322/Expected:
{"name":"1sat-browser","version":"0.0.1","transport":"streamable-http","auth":"brc-31"}
The 1sat mcp-proxy Command
The .mcp.json runs 1sat mcp-proxy. This command:
- Bridges stdin/stdout (MCP protocol) to the wallet's HTTP server
- Handles BRC-103/104 authentication automatically
- Generates and stores identity keys on first run at
~/.1sat-wallet/mcp-agent.key
For manual testing: 1sat mcp-proxy
Common Agent Workflows
Check balance then send BSV
wallet_balance— get current balancewallet_send_bsv— send to recipientwallet_balance— confirm new balance
Browse ordinals and inspect an inscription
wallet_ordinals— list owned ordinalsinscription_metadata— get full metadata for an inscriptionbrowser_navigatewith1sat://ordinals/gallery— open visual gallery
Token portfolio and marketplace
wallet_tokens— list owned BSV-21 tokenstoken_balances— balance for a specific tickermarketplace_listings— current OrdLock listings
Open a wallet page
browser_navigate with any 1sat:// URL:
1sat://wallet/send— send flow1sat://ordinals/gallery— collection1sat://identity/profile— BAP identity
Read page content
browser_navigate— load a pagebrowser_get_page_text— extract textbrowser_execute_js— deeper inspection
Available Tools
Browser Control
| Tool | Description |
|---|---|
browser_open |
Open a URL in a new browser window |
browser_close |
Close a browser window |
browser_list_windows |
List all open browser windows |
browser_navigate |
Navigate current window to a URL |
browser_go_back |
Go back in browser history |
browser_go_forward |
Go forward in browser history |
browser_execute_js |
Execute JavaScript in the browser context |
browser_get_page_text |
Get the text content of the current page |
Tab Management
| Tool | Description |
|---|---|
tab_list |
List all open tabs |
tab_create |
Create a new tab |
tab_close |
Close a tab |
tab_navigate |
Navigate a tab to a URL |
tab_activate |
Switch to a tab |
tab_go_back |
Go back in a tab's history |
tab_reload |
Reload a tab |
Main WebView Control
| Tool | Description |
|---|---|
mainview_eval |
Execute JavaScript in the main wallet WebView and return the result (code is wrapped in a function; use return) |
mainview_url |
Get the current URL loaded in the main WebView |
Blockchain Data
| Tool | Description |
|---|---|
inscription_metadata |
Get metadata for an inscription (via ORDFS) |
marketplace_listings |
Query OrdLock marketplace listings |
token_balances |
Get BSV-21 token balances |
listing_lookup |
Look up a specific marketplace listing |
Wallet Operations
| Tool | Description |
|---|---|
wallet_status |
Get wallet lock/unlock status |
wallet_balance |
Get BSV balance |
wallet_identity |
Get the wallet's BAP identity |
wallet_ordinals |
List owned ordinals/inscriptions |
wallet_tokens |
List owned BSV-21 tokens |
wallet_send_bsv |
Send BSV to an address |
Logs
| Tool | Description |
|---|---|
wallet_logs |
Query recent application log events (filter by context — startup, auth, mcp, rpc, stack, tls, shutdown — or event name; newest first) |
Internal URLs
1sat://wallet/overview— wallet dashboard1sat://wallet/send— send BSV flow1sat://wallet/receive— receive address + QR1sat://wallet/history— transaction history1sat://ordinals/gallery— ordinals collection1sat://tokens/all— token portfolio1sat://identity/profile— BAP identity1sat://settings— app settings1sat://social/feed— BSV social timeline1sat://chat— messaging
Troubleshooting
Tools not available
If MCP tools aren't appearing in Claude Code:
- Ensure the 1Sat wallet app is running. The MCP server starts when the app launches.
- Check the server is reachable:
curl -s http://127.0.0.1:3322/ - Restart Claude Code after installing the plugin to pick up
.mcp.json. - Check for port conflicts — another process may be using port 3322.
"Server not reachable" error
The 1sat mcp-proxy exits with code 1 if it can't reach 127.0.0.1:3322:
- The wallet app is not running, OR
- The MCP server hasn't started yet (give it a few seconds after launch)
Launch the 1Sat wallet app and unlock it, then restart Claude Code.
Wallet operations fail
If wallet_balance, wallet_ordinals, etc. return errors:
- The wallet may be locked — the MCP server runs but wallet ops require unlock
- Use
wallet_statusto check — iflocked, the user needs to unlock via Touch ID in the app