Submit
opldotdev

BSV MCP

Community opldotdev
Updated

An MCP Server for Bitcoin SV

BSV MCP

BSV MCP connects your AI assistant to Bitcoin SV. Ask it to check a transaction, show your balance, send a payment, or create and trade ordinals (content recorded on the blockchain).

Documentation · All tools · npm · Issues

Install

Install Bun to run the server and Node.js for the npx commands below, then add it to your client:

# Codex
codex mcp add bsv-mcp -- npx -y bsv-mcp@latest --stdio

# Claude Code
claude mcp add --transport stdio bsv-mcp -- npx -y bsv-mcp@latest --stdio

# Grok Build
grok plugin install b-open-io/bsv-mcp --trust

Choose one command. For Cursor or Claude Desktop, use this server configuration:

{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "bsv-mcp@latest", "--stdio"]
    }
  }
}

Restart your client, then ask: “Run bsv_status and explain what is available.”Local stdio needs no Sigma account or OAuth sign-in. It is also the default whenno transport is specified. Existing self-hosted HTTP remains opt-in throughTRANSPORT=http; the deployed hosted endpoint is unchanged.

For the Codex desktop plugin, add b-open-io/claude-plugins in the pluginmarketplace and install BSV MCP. The plugin starts the local npm executableand requires Node.js and Bun. Claude Code and Grok plugins bundle the local server andrequire Bun. Choose one registration to avoid duplicate tools.

Connect a wallet

Ask your assistant to run wallet_onboarding. Create, import or unlock a Vaultin the local browser. Back it up before funding. Enter passwords only in thelocal setup UI, never in chat. After a server restart, unlock it again.

To use an existing BRC-100 wallet, configure its signing API instead:

{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "bsv-mcp@latest", "--stdio"],
      "env": {
        "BRC100_WALLET_URL": "http://127.0.0.1:3321",
        "BRC100_WALLET_ORIGINATOR": "bsv-mcp.local"
      }
    }
  }
}

The wallet keeps its keys and controls permission requests. Its signing API isseparate from a wallet-storage endpoint. See wallet setupfor network settings, account selection and project roles.

The package also includes the Bun-based bsv-mcp-local launcher for explicit external,legacy embedded and project configurations. Source-checkout examples live inthe installation guide.

MCP protocol compatibility

Protocol revision 2026-07-28 is preferred, with supported 2025 clientsaccepted automatically on stdio and HTTP. No compatibility override is needed.Set MCP_LEGACY_COMPATIBILITY=false only to require modern clients. Thissetting also passes through the local launcher. The installed desktop clientwas verified using legacy requests; modern support is tested separately.

Modern clients support wallet operations and request-scoped approval. Approvalcontinuations retain the original operation and bind to its authenticated user,arguments, and expiry. Decline, cancellation, or session revocation stops theoperation; replaying a continuation does not repeat a transaction. A clientwithout form elicitation cannot approve a spend. External wallets retain theirown signer permission flow. The hosted route exposes public reads only.

For the split SDK v2 client:

const client = new Client(
  { name: "my-app", version: "1" },
  { versionNegotiation: { mode: "auto" }, capabilities: { elicitation: { form: {} } } },
);

Register a real human approval handler before using approval-dependent tools.Legacy protocol compatibility is enabled by default; the connected client must support the approval flow needed by the requested tool.

The full tool catalog remains the default and is capability-derived: walletmode, enabled modules, account context, and the selected profile determine whattools/list returns. The checked-in manifest is a synthetic baseline for oneconfigured server, not a promise of a fixed default count. SetMCP_TOOL_CATALOG=compact only to opt into bounded read families; compact modeuses the same underlying handlers. Tool availability stilldepends on wallet mode and enabled modules. Its baseline read families arebsv_read, ordinals_read, wallet_read, and utility, each with a boundedoperation enum; unknown operations are rejected. Eligible sessions also exposeseparate mutating wallet_setup and wallet_payments families. See the MCP clientprotocol support guide for the per-familyoperation bounds, endpoint contracts, MCP Apps compatibility, and validationstatus.

Social

Two tools cover social operations in both full and compact catalogs:

  • bsocial_read: posts, replies, search, likes, friends, channels, messages, videos, and raw action history.
  • bsocial_publish: posts/replies, reposts, likes/unlikes, follows/unfollows, friend/unfriend records, messages, and video records. Tags and attachments use separate, independently signed outputs.
{"action":{"type":"post","content":"Hello Bitcoin","tags":["bitcoin"]},"preview":true}

Preview returns unsigned outputs without using keys or spending. Remove preview to publish through the selected identity wallet's existing permissions. Messages are public unless their content was encrypted beforehand; a recipient context does not encrypt them. Friend records advertise a communication public key from an established key-agreement workflow.

See the social guide for examples and migration from the old tool names. PUBLIC_BMAP_URL is the indexer server root (with /social and /q routes), not a wallet or identity API. Raw follow/unfollow records are event history, not a claim about current relationship state.

Local wallet modes

External mode connects to an existing BRC-100 signer. The signer keeps theprivate keys, wallet storage, and permission decisions; BSV MCP receives onlythe SDK signer interface. Embedded mode uses an encrypted local Vault wallet.The wallet-ready screen displays an interactive cloud of the connected session’savailable tools, generated from its live catalog.

When setup is needed, wallet_onboarding opens the private browser flow tocreate, import, or unlock it. The selected account's database and storageconfiguration remain in use. The launcher's existing-account embedded modestill supplies BSV_MCP_PASSWORD at runtime.Project mode opens every explicitly assigned role: payments,identity-signing, one-sat, and encryption. It requires paired projectselectors and BSV_MCP_PASSWORD at runtime; set VAULT_PATH when the Vaultmodule does not provide a default path. Bindings pin the selected public keyand support direct keys, BRC-42 children, and BRC-157/Yours profile leaves.Changing the project binding or expiring its session revokes captured handles.Derived keys have separate storage; selecting the account's payment root keepsits existing database and deposit prefix.

BRC-100 tools accept walletRole (payments, identity, ordinals, orencryption). Method defaults select the matching role, and sign/abort actioncontinuations retain their originating wallet and authenticated user. Anunassigned role fails rather than borrowing another key. BAP tools use theidentity wallet for publication, rotation, attestations, and profiles withoutexporting an xprv. That wallet also funds those transactions and retains BAPrecords. Signed BSocial posts and SIGMA inscriptions use the configured identity.

External registrations can use the same project root/ID pair to derive anisolated permission origin, without a Vault password. OptionalBRC100_WALLET_PUBLIC_KEY pins the signer identity. BRC100_WALLET_ROLES is aJSON object selecting independent role endpoints and public-key pins; seeexternal signer configuration. The source launcheraccepts external --project-root /absolute/project --project-id project.example.It defaults to disabled broadcasting; set DISABLE_BROADCASTING=false in itsruntime environment to enable transaction tools with the signer's approval.

Each mode has its own process environment and should be registered as a separateserver when you need to switch between them. Use only the registrations needed by the project.

Embedded wallets can list pending PeerPay payments and receive a selectedpayment with wallet_peerPayments. Receiving requires a message ID andacknowledges the message only after the wallet accepts it. These operations donot pay MessageBox service fees. External signers and Droplit do not expose this tool. Project sessions requirean assigned payment role.

Find a skill

Use utils_find_skills with a short keyword query to find skills in the bOpencatalog. It returns up to five descriptions and links to versioned SKILL.mdfiles. It does not download skill contents or install plugins. In compact mode,select utils_find_skills from the utility tool.

The static tutorial prompts and BRC/BitCom resource catalog have been retired.Use the skill finder for those references. Changelog, JungleBus documentation,and the dashboard app resource remain available.

Bring your wallet and infrastructure

Connect a compatible existing wallet with BRC100_WALLET_URL, or use the localVault browser setup (wallet_onboarding). BSV_MCP_PASSWORD is only forheadless agents: set it in the process environment for that session, never inMCP client configuration. PRIVATE_KEY_WIF and IDENTITY_KEY_WIF aremigration sources, not live signing keys; import them into Vault and remove theplaintext copies. Startup never creates keys. See the wallet setup guide forthe required wallet API and configuration.

The default 1Sat API backend is https://api.1sat.app. New mainnet embeddedaccounts use https://wallet.1sat.app for wallet storage by default; testnetaccounts do not select a remote storage provider unless configured. OverrideONESAT_API_URL for API services and REMOTE_STORAGE_URL for wallet storage;these are separate settings. Available tools depend on wallet mode and enabledmodules.

Development

bun install
bun run dev          # Website
bun run build:all    # MCP server and dashboard
# Supply BRC100_WALLET_URL in the host environment before this launch.
bun --no-env-file scripts/local-mcp-launcher.ts external # Source-checkout local launch
bun test

Experimental software; APIs may change. Keep a wallet backup. If a transaction request times out, check whether it succeeded before sending it again. MIT licensed.

Preparing a release package

package.json "files" is the tarball. prepack runs bun run build:all.Publish with bun publish. Compile-time libraries are devDependencies;consumers get the bundled dist/ files, not a second copy of the source tree.

MCP Server · Populars

MCP Server · New