Skip to main content
Glama
Bitcoin SV MCP Server

Bitcoin SV MCP Server

by opldotdev

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 when no transport is specified. Existing self-hosted HTTP remains opt-in through TRANSPORT=http; the deployed hosted endpoint is unchanged.

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

Related MCP server: MNEE MCP Server

Connect a wallet

Ask your assistant to run wallet_onboarding. Create, import or unlock a Vault in the local browser. Back it up before funding. Enter passwords only in the local 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 is separate from a wallet-storage endpoint. See wallet setup for 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 in the installation guide.

MCP protocol compatibility

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

Modern clients support wallet operations and request-scoped approval. Approval continuations retain the original operation and bind to its authenticated user, arguments, and expiry. Decline, cancellation, or session revocation stops the operation; replaying a continuation does not repeat a transaction. A client without form elicitation cannot approve a spend. External wallets retain their own 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: wallet mode, enabled modules, account context, and the selected profile determine what tools/list returns. The checked-in manifest is a synthetic baseline for one configured server, not a promise of a fixed default count. Set MCP_TOOL_CATALOG=compact only to opt into bounded read families; compact mode uses the same underlying handlers. Tool availability still depends on wallet mode and enabled modules. Its baseline read families are bsv_read, ordinals_read, wallet_read, and utility, each with a bounded operation enum; unknown operations are rejected. Eligible sessions also expose separate mutating wallet_setup and wallet_payments families. See the MCP client protocol support guide for the per-family operation bounds, endpoint contracts, MCP Apps compatibility, and validation status.

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 the private keys, wallet storage, and permission decisions; BSV MCP receives only the SDK signer interface. Embedded mode uses an encrypted local Vault wallet. The wallet-ready screen displays an interactive cloud of the connected session’s available tools, generated from its live catalog.

When setup is needed, wallet_onboarding opens the private browser flow to create, import, or unlock it. The selected account's database and storage configuration remain in use. The launcher's existing-account embedded mode still supplies BSV_MCP_PASSWORD at runtime. Project mode opens every explicitly assigned role: payments, identity-signing, one-sat, and encryption. It requires paired project selectors and BSV_MCP_PASSWORD at runtime; set VAULT_PATH when the Vault module does not provide a default path. Bindings pin the selected public key and 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 keeps its existing database and deposit prefix.

BRC-100 tools accept walletRole (payments, identity, ordinals, or encryption). Method defaults select the matching role, and sign/abort action continuations retain their originating wallet and authenticated user. An unassigned role fails rather than borrowing another key. BAP tools use the identity wallet for publication, rotation, attestations, and profiles without exporting an xprv. That wallet also funds those transactions and retains BAP records. Signed BSocial posts and SIGMA inscriptions use the configured identity.

External registrations can use the same project root/ID pair to derive an isolated permission origin, without a Vault password. Optional BRC100_WALLET_PUBLIC_KEY pins the signer identity. BRC100_WALLET_ROLES is a JSON object selecting independent role endpoints and public-key pins; see external signer configuration. The source launcher accepts external --project-root /absolute/project --project-id project.example. It defaults to disabled broadcasting; set DISABLE_BROADCASTING=false in its runtime environment to enable transaction tools with the signer's approval.

Each mode has its own process environment and should be registered as a separate server 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 selected payment with wallet_peerPayments. Receiving requires a message ID and acknowledges the message only after the wallet accepts it. These operations do not pay MessageBox service fees. External signers and Droplit do not expose this tool. Project sessions require an assigned payment role.

Find a skill

Use utils_find_skills with a short keyword query to find skills in the bOpen catalog. It returns up to five descriptions and links to versioned SKILL.md files. 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 local Vault browser setup (wallet_onboarding). BSV_MCP_PASSWORD is only for headless agents: set it in the process environment for that session, never in MCP client configuration. PRIVATE_KEY_WIF and IDENTITY_KEY_WIF are migration sources, not live signing keys; import them into Vault and remove the plaintext copies. Startup never creates keys. See the wallet setup guide for the required wallet API and configuration.

The default 1Sat API backend is https://api.1sat.app. New mainnet embedded accounts use https://wallet.1sat.app for wallet storage by default; testnet accounts do not select a remote storage provider unless configured. Override ONESAT_API_URL for API services and REMOTE_STORAGE_URL for wallet storage; these are separate settings. Available tools depend on wallet mode and enabled modules.

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.

Available Tools

9 tools
bsv_decodeTransactionA

Decodes and analyzes Bitcoin SV transactions to provide detailed insights. This powerful tool accepts either a transaction ID or raw transaction data and returns comprehensive information including inputs, outputs, fee calculations, script details, and blockchain context. Supports both hex and base64 encoded transactions and automatically fetches additional on-chain data when available.

Inputs: args (required).

bsv_exploreA

Explore Bitcoin SV blockchain data using the WhatsOnChain API. Access multiple data types:

CHAIN DATA:

  • chain_info: Network stats, difficulty, and chain work

  • chain_tips: Current chain tips including heights and states

  • circulating_supply: Current BSV circulating supply

  • peer_info: Connected peer statistics

BLOCK DATA:

  • block_by_hash: Complete block data via hash (requires blockHash parameter)

  • block_by_height: Complete block data via height (requires blockHeight parameter)

  • tag_count_by_height: Stats on tag count for a specific block via height (requires blockHeight parameter)

  • block_headers: Retrieves the last 10 block headers

  • block_pages: Retrieves pages of transaction IDs for large blocks (requires blockHash and optional pageNumber)

STATS DATA:

  • block_stats_by_height: Block statistics for a specific height (requires blockHeight parameter)

  • block_miner_stats: Block mining statistics for a time period (optional days parameter, default 7)

  • miner_summary_stats: Summary of mining statistics (optional days parameter, default 7)

TRANSACTION DATA:

  • tx_by_hash: Detailed transaction data (requires txHash parameter)

  • tx_raw: Raw transaction hex data (requires txHash parameter)

  • tx_receipt: Transaction receipt (requires txHash parameter)

  • bulk_tx_details: Bulk transaction details (requires txids parameter as array of transaction hashes)

ADDRESS DATA:

  • address_history: Transaction history for address (requires address parameter, optional limit)

  • address_utxos: Unspent outputs for address (requires address parameter)

NETWORK:

  • health: API health check

Use the appropriate parameters for each endpoint type and specify 'main' or 'test' network.

Inputs: args (required).

bsv_getPriceA

Retrieves the current price of Bitcoin SV (BSV) in USD from a reliable exchange API. This tool provides real-time market data that can be used for calculating transaction values, monitoring market conditions, or converting between BSV and fiat currencies.

Inputs: args.

ordinals_getInscriptionA

Retrieves detailed information about a specific ordinal inscription by its outpoint. Returns complete inscription data including content type, file information, inscription origin, and current status. Useful for verifying NFT authenticity or retrieving metadata about digital artifacts.

Inputs: args (required).

ordinals_getTokenByIdOrTickerB

Retrieves detailed information about a specific BSV-20 token by its ID or ticker symbol. Returns complete token data including ticker symbol, supply information, decimals, and current status. This tool is useful for verifying token authenticity or checking supply metrics.

Inputs: args (required).

ordinals_marketListingsC

Retrieves current marketplace listings for Bitcoin SV ordinals with flexible filtering. Supports multiple asset types (NFTs, BSV-20 tokens, BSV-21 tokens) through a unified interface. Results include listing prices, details about the assets, and seller information.

Inputs: args (required).

ordinals_marketSalesB

Retrieves recent sales data for BSV-20 and BSV-21 tokens on the ordinals marketplace. This tool provides insights into market activity, including sale prices, transaction details, and token information. Supports filtering by token ID, ticker symbol, or seller address to help analyze market trends and track specific token sales.

Inputs: args (required).

ordinals_searchInscriptionsB

Searches for Bitcoin SV ordinal inscriptions using flexible criteria. This powerful search tool supports filtering by address, inscription content, MIME type, MAP fields, and other parameters. Results include detailed information about each matched inscription. Ideal for discovering NFTs and exploring the ordinals ecosystem.

Inputs: args (required).

utils_convertDataA

Converts data between different encodings (utf8, hex, base64, binary). Useful for transforming data formats when working with blockchain data, encryption, or file processing.

Parameters:

  • data (required): The string to convert

  • from (required): Source encoding format (utf8, hex, base64, or binary)

  • to (required): Target encoding format (utf8, hex, base64, or binary)

Example usage:

  • UTF-8 to hex: {"data": "hello world", "from": "utf8", "to": "hex"} → 68656c6c6f20776f726c64

  • UTF-8 to base64: {"data": "Hello World", "from": "utf8", "to": "base64"} → SGVsbG8gV29ybGQ=

  • base64 to UTF-8: {"data": "SGVsbG8gV29ybGQ=", "from": "base64", "to": "utf8"} → Hello World

  • hex to base64: {"data": "68656c6c6f20776f726c64", "from": "hex", "to": "base64"} → aGVsbG8gd29ybGQ=

Notes:

  • All parameters are required

  • The tool returns the converted data as a string

  • For binary conversion, data is represented as an array of byte values

Inputs: args (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 9 tools

    Disambiguation3/5

    The tools have clear domains (BSV blockchain, ordinals, utilities), but within the bsv_explore tool, many sub-endpoints (e.g., block_by_hash, address_history) are bundled under one tool, which could cause confusion as they represent distinct operations. Other tools like ordinals_getInscription and ordinals_searchInscriptions have overlapping purposes but are differentiated by specific vs. search functionality.

    Naming Consistency4/5

    Most tools follow a consistent prefix_snake_case pattern (e.g., bsv_decodeTransaction, ordinals_getInscription, utils_convertData), with clear domain prefixes. However, bsv_explore is an outlier as it groups multiple operations under one name, deviating from the single-action-per-tool convention seen elsewhere.

    Tool Count4/5

    With 9 tools, the count is reasonable for covering Bitcoin SV blockchain, ordinals, and utilities. However, the bsv_explore tool effectively bundles many sub-operations, making the actual functionality count higher than 9, which could be seen as slightly heavy but still manageable.

    Completeness4/5

    The toolset covers key areas: transaction decoding, blockchain exploration, price data, ordinals (inscriptions, tokens, marketplace), and data conversion. Minor gaps include lack of tools for creating or broadcasting transactions, and deeper wallet or smart contract operations, but core read-only and analysis functions are well-represented for the domain.

    Maintenance

    ActivityNo data
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to interact with MNEE stablecoin on Bitcoin SV, including checking balances, transferring tokens, and querying transaction history in both sandbox and production environments.
      -
    • A
      license
      C
      quality
      D
      maintenance
      Enables AI applications to interact with the Bitcoin Network, manage wallets, check balances, convert prices, and send transactions.
      4
      179 npm
      6
      MIT