# Desktop MCP

> Control the running 1Sat desktop wallet via MCP. Use this proactively whenever the user mentions their wallet, BSV balance, ordinals, inscriptions, tokens, sending BSV, browsing the 1Sat app, or any blockchain task that could be done through the wallet UI. The 1sat plugin ships .mcp.json automatically — if the plugin is installed and the wallet app is running, tools are available immediately with no manual setup. Requires the 1Sat wallet-desktop app to be running.

- Skill: `b-open-io/desktop-mcp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add b-open-io/desktop-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/b-open-io/desktop-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: b-open-io (https://skillmd.com/u/b-open-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/b-open-io/desktop-mcp

---


# 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

1. **Install the 1Sat CLI globally:**
   ```bash
   bun install -g @1sat/cli
   ```

2. **Launch the 1Sat wallet desktop app.** The MCP server starts on `127.0.0.1:3322` automatically.

3. **MCP tools appear in Claude Code.** The 1sat plugin ships `.mcp.json`. Restart Claude Code to pick it up.

   Verify the server is reachable:
   ```bash
   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
1. `wallet_balance` — get current balance
2. `wallet_send_bsv` — send to recipient
3. `wallet_balance` — confirm new balance

### Browse ordinals and inspect an inscription
1. `wallet_ordinals` — list owned ordinals
2. `inscription_metadata` — get full metadata for an inscription
3. `browser_navigate` with `1sat://ordinals/gallery` — open visual gallery

### Token portfolio and marketplace
1. `wallet_tokens` — list owned BSV-21 tokens
2. `token_balances` — balance for a specific ticker
3. `marketplace_listings` — current OrdLock listings

### Open a wallet page
`browser_navigate` with any `1sat://` URL:
- `1sat://wallet/send` — send flow
- `1sat://ordinals/gallery` — collection
- `1sat://identity/profile` — BAP identity

### Read page content
1. `browser_navigate` — load a page
2. `browser_get_page_text` — extract text
3. `browser_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 dashboard
- `1sat://wallet/send` — send BSV flow
- `1sat://wallet/receive` — receive address + QR
- `1sat://wallet/history` — transaction history
- `1sat://ordinals/gallery` — ordinals collection
- `1sat://tokens/all` — token portfolio
- `1sat://identity/profile` — BAP identity
- `1sat://settings` — app settings
- `1sat://social/feed` — BSV social timeline
- `1sat://chat` — messaging

## Troubleshooting

### Tools not available

If MCP tools aren't appearing in Claude Code:

1. **Ensure the 1Sat wallet app is running.** The MCP server starts when the app launches.
2. **Check the server is reachable:** `curl -s http://127.0.0.1:3322/`
3. **Restart Claude Code** after installing the plugin to pick up `.mcp.json`.
4. **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_status` to check — if `locked`, the user needs to unlock via Touch ID in the app