Bitcoin SV MCP Server

⚠️ NOTICE: Experimental Work in Progress
This project is in an early experimental stage. Features may change, and the API is not yet stable. Contributions, feedback, and bug reports are welcome! Feel free to open issues or submit pull requests.

A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework. This library provides wallet, ordinals, and utility functions for BSV blockchain interaction.

Installation Options

Option 1: Hosted Version (FREE - No BSV Required!)

The easiest way to get started! Use our hosted version with OAuth 2.1 authentication:

Configure: Add the MCP server configuration to your IDE
Authenticate: Sign in with your Bitcoin wallet via sigma-auth
Use: Start using BSV features immediately - no BSV needed!

{
  "mcpServers": {
    "bsv-mcp-hosted": {
      "url": "https://bsv-mcp.rohenaz.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

To get your access token, authenticate at https://auth.sigmaidentity.com

Benefits:

✅ No Bitcoin required - we pay for everything
✅ Secure OAuth 2.1 authentication with Bitcoin signatures
✅ Instant setup - no installation needed
✅ Always up-to-date
✅ Global availability via Cloudflare

Option 2: Self-Hosted Installation

Prerequisites

**Use Bun (Optional but recommended)

This project is built using Bun, a fast JavaScript runtime and package manager. While Bun is recommended for best performance, the server can also run with Node.js and npm as Bun is designed to be backward compatible with node.

Installing Bun

macOS (using Homebrew):

brew install oven-sh/bun/bun

macOS/Linux/WSL (using installer script):

curl -fsSL https://bun.sh/install | bash

Windows: Windows users should use WSL (Windows Subsystem for Linux) or Docker to run Bun.

Node.js and npm will also work but may not offer the same performance benefits.

Connecting to MCP Clients

This server implements the Model Context Protocol (MCP), allowing AI assistants to utilize Bitcoin SV functionalities. You can connect this server to various MCP-compatible clients.

MCP Configuration Example

Note: The PRIVATE_KEY_WIF environment variable is now optional. Without it, the server runs in limited mode with educational resources and non-wallet tools available. Wallet and MNEE token operations require a valid private key. You can also set the IDENTITY_KEY_WIF environment variable to enable sigma-protocol signing of ordinals inscriptions for authentication, curation, and web-of-trust.

Claude Code

To use the BSV MCP server with Claude Code:

# Using bunx (recommended)
claude mcp add bsv-mcp "bunx bsv-mcp@latest"

# Or using npx
claude mcp add bsv-mcp "npx bsv-mcp@latest"

To add with environment variables:

claude mcp add bsv-mcp "bunx bsv-mcp@latest" -e PRIVATE_KEY_WIF=your_key -e IDENTITY_KEY_WIF=your_identity_key

For encrypted key storage (recommended):

claude mcp add bsv-mcp "bunx bsv-mcp@latest" -e BSV_MCP_PASSPHRASE="your-secure-passphrase"

Note: The server automatically runs in stdio mode when used with Claude Code CLI.

Cursor

Quick Install: Click the button above to automatically add the BSV MCP server to Cursor! This will install the server with the basic configuration using bunx bsv-mcp@latest.

Manual Setup: To manually configure the BSV MCP server with Cursor:

Install Cursor if you haven't already
Open Cursor and navigate to Settings → Extensions → Model Context Protocol
Click "Add a new global MCP server"
Enter the following configuration in JSON format:

{
  "mcpServers": {
    "Bitcoin SV": {
      "command": "bunx",
      "args": [
        "bsv-mcp@latest"
      ],
      "env": {
        "PRIVATE_KEY_WIF": "<your_private_key_wif>",
        "IDENTITY_KEY_WIF": "<your_identity_key_wif>"
      }
    }
  }
}

Replace <your_private_key_wif> with your actual private key WIF (keep this secure!) If you dont have one you can leave this off for now but you wont be able to use tools that require a wallet. <your_identity_key_wif> is also optional. It will sign 1Sat Ordinals with Sigma protocol using the provided identity key.
Click "Save"

The BSV tools will now be available to Cursor's AI assistant under the "Bitcoin SV" namespace.

Alternative for npm users

If you prefer to use npm instead of Bun:

{
  "mcpServers": {
    "Bitcoin SV": {
      "command": "npx",
      "args": [
        "bsv-mcp@latest"
      ],
      "env": {
        "PRIVATE_KEY_WIF": "<your_private_key_wif>",
        "IDENTITY_KEY_WIF": "<your_identity_key_wif>"
      }
    }
  }
}

Claude for Desktop

To connect this server to Claude for Desktop:

Open Claude for Desktop and go to Claude > Settings > Developer
Click "Edit Config".

Open the Claude configuration json file in your favorite text editor. If you prefer to do it from the cli:

# macOS/Linux
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
code %APPDATA%\Claude\claude_desktop_config.json

Add the BSV MCP server to your configuration:

{
  "mcpServers": {
    "Bitcoin SV": {
      "command": "bun",
      "args": [
        "run", "bsv-mcp@latest"
      ],
      "env": {
        "PRIVATE_KEY_WIF": "<your_private_key_wif>",
        "IDENTITY_KEY_WIF": "<your_identity_key_wif>"
      }
    }
  }
}

Replace <your_private_key_wif> with your actual private key WIF
Save the file and restart Claude for Desktop
The BSV tools will appear when you click the tools icon (hammer) in Claude for Desktop

Alternative for npm users (Claude)

If you prefer to use npm instead of Bun, replace the "command" field with "npx".

VS Code (CLI Method)

If you prefer using the command line, you can add the BSV MCP server to VS Code (which uses the same underlying settings as Cursor) directly:

Using Bun (Recommended):

code --add-mcp '{"name":"Bitcoin SV","command":"bunx","args":["bsv-mcp@latest"],"env":{"PRIVATE_KEY_WIF":"<your_private_key_wif>","IDENTITY_KEY_WIF":"<your_identity_key_wif>"}}'

Using Node.js/npm:

code --add-mcp '{"name":"Bitcoin SV","command":"npx","args":["bsv-mcp@latest"],"env":{"PRIVATE_KEY_WIF":"<your_private_key_wif>","IDENTITY_KEY_WIF":"<your_identity_key_wif>"}}'

Replace <your_private_key_wif> with your actual private key WIF (optional, required for wallet tools).
Replace <your_identity_key_wif> with your identity key WIF (optional, enables Sigma protocol signing).
Ensure the code command is in your system's PATH (it usually is if VS Code was installed normally).

This command adds the server configuration to your VS Code settings.json file under the mcp.servers key.

Available Tools

The toolkit is organized into several categories:

Wallet Tools

Wallet tools provide core BSV wallet functionality:

Tool Name	Description	Example Output
`wallet_getPublicKey`	Retrieves a public key for a specified protocol and key ID	`{"publicKey":"032d0c73eb9270e9e009fd1f9dd77e19cf764fbad5f799560c4e8fd414e40d6fc2"}`
`wallet_createSignature`	Creates a cryptographic signature for the provided data	`{"signature":[144,124,85,193,226,45,140,249,9,177,11,167,33,215,209,38,...]}`
`wallet_verifySignature`	Verifies a cryptographic signature against the provided data	`{"isValid":true}`
`wallet_encryption`	Combined tool for encrypting and decrypting data using the wallet's cryptographic keys. Examples: 1. Encrypt text: `"Encrypt this message: Hello World"` 2. Decrypt data: `"Decrypt this data that was previously encrypted for me"`	Encrypt: `{"ciphertext":[89,32,155,38,125,22,49,226,26,...]}` Decrypt: `{"plaintext":"hello world"}`
`wallet_getAddress`	Returns a BSV address for the current wallet or a derived path	`{"address":"1ExampleBsvAddressXXXXXXXXXXXXXXXXX","status":"ok"}`
`wallet_sendToAddress`	Sends BSV to a specified address (supports BSV or USD amounts)	`{"status":"success","txid":"a1b2c3d4e5f6...","satoshis":1000000}`
`wallet_purchaseListing`	Purchases NFTs or BSV-20/BSV-21 tokens from marketplace listings	`{"status":"success","txid":"a1b2c3d4e5f6...","type":"nft","origin":"abcdef123456..."}`
`wallet_createOrdinals`	Creates and inscribes ordinals on the BSV blockchain	`{"txid":"a1b2c3d4e5f6...","inscriptionAddress":"1ExampleAddress...","contentType":"image/png"}`

BSV Tools

Tools for interacting with the BSV blockchain and network:

Tool Name	Description	Example Output
`bsv_getPrice`	Gets the current BSV price from an exchange API	`Current BSV price: $38.75 USD`
`bsv_decodeTransaction`	Decodes a BSV transaction and returns detailed information	`{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,"inputs":[...],"outputs":[...]}`
`bsv_explore`	Comprehensive blockchain explorer tool accessing WhatsOnChain API endpoints	`{"chain_info":{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"0000000000..."}}`

BSocial Tools

Tools for social interactions on the BSV blockchain (requires wallet):

Tool Name	Description	Example Output
`bsocial_createPost`	Creates a social post on the BSV blockchain using B:// and MAP protocols	`{"success":true,"txid":"a1b2c3d4e5f6...","rawTx":"0100000001..."}`
`bsocial_readPosts`	Reads social posts from the BSV blockchain with filtering options	`Post 1:\n TX ID: a1b2c3...\n Content: Hello BSV!\n Type: text/plain\n Author: 1Example...`

Ordinals Tools

Tools for working with ordinals (NFTs) on BSV:

Tool Name	Description	Example Output
`ordinals_getInscription`	Retrieves detailed information about a specific inscription	`{"id":"a1b2c3d4e5f6...","origin":"a1b2c3d4e5f6...","contentType":"image/png","content":"iVBORw0KGgoAAA..."}`
`ordinals_searchInscriptions`	Searches for inscriptions based on various criteria	`{"results":[{"id":"a1b2c3...","contentType":"image/png","owner":"1Example..."},...]}`
`ordinals_marketListings`	Retrieves market listings for NFTs, BSV-20, and BSV-21 tokens with unified interface	`{"results":[{"txid":"a1b2c3...","price":9990000,"tick":"PEPE","listing":true},...]}`
`ordinals_marketSales`	Gets information about BSV-20 and BSV-21 token market sales	`{"results":[{"txid":"a1b2c3...","price":34710050,"tick":"$BTC","sale":true},...]}`
`ordinals_getTokenByIdOrTicker`	Retrieves details about a specific BSV20 token by ID	`{"tick":"PEPE","max":"21000000","lim":"1000","dec":"2"}`

Utility Tools

General-purpose utility functions:

Tool Name	Description	Example Output
`utils_convertData`	Converts data between different encodings (utf8, hex, base64, binary).

Args:
- data (string, required): The data string to be converted.
- from (string, required): Source encoding format (utf8, hex, base64, or binary).
- to (string, required): Target encoding format (utf8, hex, base64, or binary).
Returns: The converted data as a string.

BAP (Bitcoin Attestation Protocol) Tools

Tools for interacting with BAP identities.

`bap_getId`

Retrieves a Bitcoin Attestation Protocol (BAP) identity profile using an idKey.

Args:
- idKey (string, optional): The Identity Key (Paymail or public key string) to fetch the profile for. If not provided, the tool attempts to use the server's configured identity key (derived from IDENTITY_KEY_WIF or the key file ~/.bsv-mcp/keys.json).
Returns: A JSON string containing the BAP identity data if found, or a message indicating that no identity was found for the given key. Returns an error if the API request fails or the key cannot be derived.

`bap_getCurrentAddress`

Retrieves the current BAP identity's Bitcoin SV address. This address is derived from the server's configured identity key.

Args: None.
Returns: A JSON object containing the address string.

`bap_generate`

Generates a new BAP HD master key (xprv) and saves it to ~/.bsv-mcp/keys.json. This key can be used as a root for deriving multiple BAP identities.

Args: None.
Returns: A JSON object with the generated xprv string and a status message, or an error message if generation/saving fails.

MNEE Tools

Tools for working with MNEE tokens:

Tool Name	Description	Example Output
`mnee_getBalance`	Retrieves the current MNEE token balance for the wallet	`{"balance": {"amount": 2900, "decimalAmount": 0.029}}`
`mnee_sendMnee`	Send MNEE tokens to a specified address. Supports both MNEE and USD amounts	`{"success": true, "txid": "d1ce853934964e6c1fe9f44c918a824f175c6ab466b966f49ebc0682a8318895", "rawtx": "0100000002a0be40d8942015f1...", "mneeAmount": 0.01, "usdAmount": "$0.01", "recipient": "15mNxEkyKJXPD8amic6oLUjS45zBKQQoLu"}`
`mnee_parseTx`	Parse an MNEE transaction to get detailed information about its operations and amounts. All amounts are in atomic units with 5 decimal precision (e.g. 1000 atomic units = 0.01 MNEE)	`{"txid": "d1ce853934964e6c1fe9f44c918a824f175c6ab466b966f49ebc0682a8318895", "environment": "production", "type": "transfer", "inputs": [{"address": "18izL7Wtm2fx3ALoRY3MkY2VFSMjArP62D", "amount": 2900}], "outputs": [{"address": "15mNxEkyKJXPD8amic6oLUjS45zBKQQoLu", "amount": 1000}, {"address": "19Vq2TV8aVhFNLQkhDMdnEQ7zT96x6F3PK", "amount": 100}, {"address": "18izL7Wtm2fx3ALoRY3MkY2VFSMjArP62D", "amount": 1800}]}`

Using the Tools with MCP

Once connected, you can use natural language to interact with Bitcoin SV through your AI assistant. Here are some example prompts:

Wallet Operations

"Get my Bitcoin SV address"
"Send 0.01 BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
"Send $5 USD worth of BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
"Send 0.01 MNEE to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
"Check my MNEE balance"
"Parse this MNEE transaction: txid"
"Encrypt this message using my wallet's keys"
"Decrypt this data that was previously encrypted for me"
"Purchase this NFT listing: txid_vout"
"Purchase this BSV-20 token listing: txid_vout"

Ordinals (NFTs)

"Show me information about the NFT with outpoint 6a89047af2cfac96da17d51ae8eb62c5f1d982be2bc4ba0d0cd2084b7ffed325_0"
"Search for Pixel Zoide NFTs"
"Show me the current marketplace listings for BSV NFTs"
"Show me BSV-20 token listings for ticker PEPE"
"Get recent BSV-20 token sales"

Collection Minting

The BSV MCP server provides a two-step process for minting ordinal collections from folders of images:

Gather Collection Info (Pre-flight check)
- "Analyze the folder /path/to/my/nft-images for collection minting"
- "Check if I can mint a collection from ./my-art-folder"
This step will:
- Validate all images in the folder
- Check your wallet balance
- Estimate total costs
- Suggest collection metadata
- Report any issues before minting
Mint Collection (Create the collection)
- "Mint a collection called 'My Art Collection' from /path/to/images with description 'Amazing digital art'"
- "Create an NFT collection from ./my-art-folder with traits: background=[red,blue,green], style=[vintage,modern]"
- "Mint collection with rarity labels: common=60%, rare=30%, legendary=10%"

Blockchain Operations

"What is the current BSV price?"
"Decode this BSV transaction: (transaction hex or ID)"
"Get the latest Bitcoin SV chain information"
"Show me block details for height 800000"
"Explore transaction history for address 1ExampleBsvAddressXXXX"
"Check unspent outputs (UTXOs) for my wallet address"
"Get details for transaction with hash a1b2c3d4e5f6..."

Data Conversion

"Convert 'Hello World' from UTF-8 to hex format"

"Create a post saying 'Hello BSV World!' on the blockchain"
"Post a markdown message: # My First On-Chain Post\n\nThis is bold and italic text"
"Read the latest social posts from the blockchain"
"Read posts by BAP identity 1SomeIdentityKey..."
"Get the post with transaction ID a1b2c3d4e5f6..."
"Show me replies to post txid a1b2c3d4e5f6..."

MCP Prompts and Resources

The BSV MCP server exposes specialized prompts and resources that provide detailed information and context about Bitcoin SV technologies. These can be accessed by AI models to enhance their understanding and capabilities.

Available Prompts

The server provides the following educational prompts that can be accessed directly via the MCP protocol:

Ordinals Prompt

Identifier: bitcoin_sv_ordinals
Description: Comprehensive information about Bitcoin SV ordinals, including what they are, how they work, and how to use them.
Usage: Ask the assistant about "Bitcoin SV ordinals" or "1Sat Ordinals" to access this information.

BSV SDK Prompts

A collection of prompts providing detailed information about the Bitcoin SV SDK:

Overview
- Identifier: bitcoin_sv_sdk_overview
- Description: General overview of the Bitcoin SV SDK, including its purpose and main components.
- Usage: "Tell me about the BSV SDK" or "What is the Bitcoin SV SDK?"
Wallet Operations
- Identifier: bitcoin_sv_sdk_wallet
- Description: Information about wallet operations in the BSV SDK.
- Usage: "How do wallet operations work in the BSV SDK?"
Transaction Building
- Identifier: bitcoin_sv_sdk_transaction
- Description: Details about transaction creation and manipulation.
- Usage: "Explain BSV SDK transaction building" or "How do I create transactions with BSV SDK?"
Authentication
- Identifier: bitcoin_sv_sdk_auth
- Description: Authentication and identity protocols in BSV SDK.
- Usage: "How does authentication work with BSV SDK?"
Cryptography
- Identifier: bitcoin_sv_sdk_cryptography
- Description: Signing, encryption, and verification functionality.
- Usage: "Explain BSV SDK cryptography features"
Scripting
- Identifier: bitcoin_sv_sdk_script
- Description: Bitcoin scripting and contract capabilities.
- Usage: "How do I work with Bitcoin scripts using the BSV SDK?"
Primitives
- Identifier: bitcoin_sv_sdk_primitives
- Description: Core data types and structures in the BSV SDK.
- Usage: "What primitives are available in the BSV SDK?"

Available Resources

The server also provides access to Bitcoin Request for Comments (BRC) specifications and documentation:

Changelog Resource

Identifier: bsv-mcp-changelog
Description: Version history and changelog for the BSV MCP server.
Usage: "Show me the BSV MCP changelog" or "What's new in the latest version?"

BRC Resources

BRCs Overview
- Identifier: brcs_readme
- Description: Overview of all Bitcoin SV protocol specifications in the BRCs repository.
- Usage: "Show me the Bitcoin SV BRCs overview"
BRCs Summary
- Identifier: brcs_summary
- Description: Table of contents for all Bitcoin SV BRCs.
- Usage: "Give me a summary of Bitcoin SV BRCs"
Specific BRC Specifications
- Identifier: brc_spec
- Description: Access specific BRC specifications by category and number.
- Usage: "Show me BRC 8 on Transaction Envelopes" or "What does BRC 1 specify?"

BRC Categories

The BRC specifications are organized into the following categories:

Wallet
Transactions
Scripts
Tokens
Overlays
Payments
Peer-to-Peer
Key Derivation
Outpoints
Opinions
State Machines
Apps

Using Prompts and Resources

AI models can use these prompts and resources to provide more accurate and detailed responses about Bitcoin SV technologies. As a user, you can:

Ask about a specific topic: "Tell me about Bitcoin SV ordinals" or "Explain BSV SDK transaction building"
Request specific BRC details: "What does BRC 8 specify?" or "Show me the BRC on Transaction Creation"
Get general overviews: "What is the BSV SDK?" or "Show me a summary of all BRCs"

These prompts and resources enhance the AI's knowledge base, enabling more technical and accurate responses even for complex Bitcoin SV topics.

How MCP Works

When you interact with an MCP-enabled AI assistant:

The AI analyzes your request and decides which tools to use
With your approval, it calls the appropriate BSV MCP tool
The server executes the requested operation on the Bitcoin SV blockchain
The results are returned to the AI assistant
The assistant presents the information in a natural, conversational way

Key Management & Security

Encrypted Key Storage (Recommended)

BSV MCP now supports encrypted key storage using bitcoin-backup for enhanced security:

Set a passphrase (minimum 8 characters):

export BSV_MCP_PASSPHRASE="your-secure-passphrase"

Automatic migration: Keys will be automatically encrypted when a passphrase is provided

Manual migration: Use the migration script:

BSV_MCP_PASSPHRASE="your-passphrase" bun run scripts/migrate-keys.ts

File locations:
- Encrypted keys: ~/.bsv-mcp/keys.bep
- Legacy keys: ~/.bsv-mcp/keys.json (deprecated)
- Automatic backup: ~/.bsv-mcp/keys.bep.backup

Security Best Practices

Use encrypted storage: Always set BSV_MCP_PASSPHRASE for production use
Strong passphrases: Use 12+ characters with mixed case, numbers, and symbols
Backup your keys: Keep secure backups of both keys and passphrase
File permissions: Key files are automatically created with restricted permissions (0600)

Environment Variables for Key Management

Variable	Description	Default
`BSV_MCP_PASSPHRASE`	Passphrase for encrypted key storage	None
`BSV_MCP_AUTO_MIGRATE`	Automatically migrate legacy keys	`false`
`BSV_MCP_KEEP_LEGACY`	Keep unencrypted keys after migration	`false`

Customization Options

The BSV MCP server can be customized using environment variables to enable or disable specific components:

Component Configuration

Environment Variable	Default	Description
`DISABLE_PROMPTS`	`false`	Set to `true` to disable all educational prompts
`DISABLE_RESOURCES`	`false`	Set to `true` to disable all resources (BRCs, changelog)
`DISABLE_TOOLS`	`false`	Set to `true` to disable all tools

Tool-Specific Configuration

Environment Variable	Default	Description
`DISABLE_WALLET_TOOLS`	`false`	Set to `true` to disable Bitcoin wallet tools
`DISABLE_MNEE_TOOLS`	`false`	Set to `true` to disable MNEE token tools
`DISABLE_BSV_TOOLS`	`false`	Set to `true` to disable BSV blockchain tools
`DISABLE_ORDINALS_TOOLS`	`false`	Set to `true` to disable Ordinals/NFT tools
`DISABLE_UTILS_TOOLS`	`false`	Set to `true` to disable utility tools
`IDENTITY_KEY_WIF`	`not set`	Optional WIF for identity key; if set, ordinals inscriptions will be signed with sigma-protocol for authentication, curation, and web-of-trust.
`DISABLE_BROADCASTING`	`false`	Set to `true` to disable transaction broadcasting; returns raw transaction hex instead - useful for testing and transaction review before broadcasting

Droplet API Configuration

The BSV MCP server supports running in Droplet API mode, which allows operation without local private keys by using a remote faucet service:

Environment Variable	Default	Description
`USE_DROPLET_API`	`false`	Set to `true` to enable Droplet API mode for remote wallet operations
`DROPLET_API_URL`	`http://localhost:4000`	Base URL for the Droplet faucet API service
`DROPLET_FAUCET_NAME`	`not set`	Name of the faucet to use (required when `USE_DROPLET_API` is true)
`TRANSPORT`	`stdio`	MCP transport mode (stdio/http) - automatically set to stdio for Claude Code compatibility

Droplet API Mode

When USE_DROPLET_API=true is set, the server operates in remote mode:

No Local Keys Required: The server doesn't need PRIVATE_KEY_WIF or local key files
Remote Wallet Operations: Transactions are funded and broadcast through the Droplet API
BSM Authentication: Uses Bitcoin Signed Message (BSM) authentication for secure API communication
Automatic Funding: The faucet automatically provides UTXOs for transactions
Seamless Integration: All existing wallet tools work transparently with the remote service

Example Droplet Configuration

# Enable Droplet API mode
USE_DROPLET_API=true
DROPLET_API_URL=https://your-droplet-service.com
DROPLET_FAUCET_NAME=your-faucet-name
TRANSPORT=stdio

This mode is particularly useful for:

Development and Testing: No need to manage local private keys
Educational Environments: Safe experimentation without real funds
Shared Environments: Multiple users can use the same faucet service
Simplified Deployment: Reduced security concerns for demonstration purposes

Examples

Run with only educational resources and prompts, no tools:

DISABLE_TOOLS=true bunx bsv-mcp@latest

Run with only BSV tools, no wallet or other functionality:

DISABLE_PROMPTS=true DISABLE_RESOURCES=true DISABLE_WALLET_TOOLS=true DISABLE_MNEE_TOOLS=true DISABLE_ORDINALS_TOOLS=true DISABLE_UTILS_TOOLS=true bunx bsv-mcp@latest

Use all tools except wallet operations:

DISABLE_WALLET_TOOLS=true bunx bsv-mcp@latest

Create transactions without broadcasting them (dry-run mode):

DISABLE_BROADCASTING=true bunx bsv-mcp@latest

Troubleshooting

If you're having issues with the BSV MCP server:

Connection Issues

Make sure Bun or Node.js is installed on your system
Verify your WIF private key is correctly set in the environment
Check that your client supports MCP and is properly configured
Look for error messages in the client's console output

Keeping Bun Up to Date

It's important to keep Bun updated to the latest version to ensure compatibility:

# Update Bun to the latest version
bun upgrade

To verify your current Bun version:

bun --version

Logging and Debugging

For Claude for Desktop, check the logs at:

# macOS/Linux
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Windows
type %APPDATA%\Claude\Logs\mcp*.log

For Cursor, check the Cursor MCP logs in Settings → Extensions → Model Context Protocol.

Recent Updates

Transaction Broadcast Control: Added DISABLE_BROADCASTING environment variable to prevent transactions from being broadcast to the network
Blockchain Explorer: Added bsv_explore tool for WhatsOnChain API access with mainnet/testnet support
Unified Tools: Merged wallet_encrypt/wallet_decrypt into single wallet_encryption tool
Enhanced Marketplace: Support for NFTs, BSV-20/21 tokens in listings, sales and purchases
Performance: Added price caching and optimized API endpoint structure
Improved Validation: Better error handling for private keys and parameters

Bitcoin SV Blockchain Explorer

The bsv_explore tool provides comprehensive access to the Bitcoin SV blockchain through the WhatsOnChain API. This powerful explorer tool allows you to query various aspects of the blockchain, including chain data, blocks, transactions, and address information.

Available Endpoints

The tool supports the following endpoint categories and specific endpoints:

Chain Data

Endpoint	Description	Required Parameters	Example Response
`chain_info`	Network statistics, difficulty, and chain work	None	`{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"0000000000..."}`
`chain_tips`	Current chain tips including heights and states	None	`[{"height":826458,"hash":"000000000000...","branchlen":0,"status":"active"}]`
`circulating_supply`	Current BSV circulating supply	None	`{"bsv":21000000}`
`peer_info`	Connected peer statistics	None	`[{"addr":"1.2.3.4:8333","services":"000000000000...","lastsend":1621234567}]`

Block Data

Endpoint	Description	Required Parameters	Example Response
`block_by_hash`	Complete block data via hash	`blockHash`	`{"hash":"000000000000...","confirmations":1000,"size":1000000,...}`
`block_by_height`	Complete block data via height	`blockHeight`	`{"hash":"000000000000...","confirmations":1000,"size":1000000,...}`
`tag_count_by_height`	Stats on tag count for a specific block	`blockHeight`	`{"tags":{"amp":3,"bitkey":5,"metanet":12,"planaria":7,"b":120}}`
`block_headers`	Retrieves the last 10 block headers	None	`[{"hash":"000000000000...","height":826458,"version":536870912,...},...]`
`block_pages`	Retrieves pages of transaction IDs for large blocks	`blockHash`, optional: `pageNumber`	`["tx1hash","tx2hash","tx3hash",...]`

Stats Data

Endpoint	Description	Required Parameters	Example Response
`block_stats_by_height`	Block statistics for a specific height	`blockHeight`	`{"size":123456,"txCount":512,"outputTotal":54.12345678,"outputTotalUsd":2345.67,...}`
`block_miner_stats`	Block mining statistics for a time period	optional: `days` (default 7)	`{"blocks":{"miner1":412,"miner2":208,...},"total":1008}`
`miner_summary_stats`	Summary of mining statistics	optional: `days` (default 7)	`{"totalBlocks":1008,"totalFees":1.23456789,"totalFeesUsd":53.67,...}`

Transaction Data

Endpoint	Description	Required Parameters	Example Response
`tx_by_hash`	Detailed transaction data	`txHash`	`{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,...}`
`tx_raw`	Raw transaction hex data	`txHash`	`"01000000012345abcdef..."`
`tx_receipt`	Transaction receipt	`txHash`	`{"blockHash":"000000000000...","blockHeight":800000,"confirmations":26458}`
`bulk_tx_details`	Retrieve multiple transactions in one request	`txids` (array)	`[{"txid":"a1b2c3d4e5f6...","version":1,...}, {"txid":"b2c3d4e5f6a7...","version":1,...}]`

Address Data

Endpoint	Description	Required Parameters	Example Response
`address_history`	Transaction history for address	`address`, optional: `limit`	`[{"tx_hash":"a1b2c3d4e5f6...","height":800000},...]`
`address_utxos`	Unspent outputs for address	`address`	`[{"tx_hash":"a1b2c3d4e5f6...","tx_pos":0,"value":100000},...]`

Network

Endpoint	Description	Required Parameters	Example Response
`health`	API health check	None	`{"status":"synced"}`

Usage Examples

The bsv_explore tool can be used with natural language prompts like:

"Get the current Bitcoin SV blockchain information"
"Show me block #800000 details"
"Get tag count statistics for block #800000"
"Fetch transaction history for address 1ExampleBsvAddressXXXXXXXX"
"Get unspent outputs for my wallet address"
"Check transaction details for txid a1b2c3d4e5f6..."
"What is the current BSV circulating supply?"
"Show me the latest block headers"
"Get transaction IDs for page 2 of a large block"
"Show me block statistics for height 800000"
"What are the mining statistics for the last 14 days?"
"Get a summary of mining activity over the past 30 days"
"Retrieve details for multiple transactions in a single query"

Under the hood, the tool accepts parameters to specify which data to retrieve:

endpoint: The specific WhatsOnChain endpoint to query (e.g., chain_info, tx_by_hash)
network: The BSV network to use (main or test)
Additional parameters as required by the specific endpoint:
- blockHash: For block_by_hash and block_pages endpoints
- blockHeight: For block_by_height, tag_count_by_height, and block_stats_by_height endpoints
- pageNumber: For block_pages endpoint (pagination)
- days: For block_miner_stats and miner_summary_stats endpoints (defaults to 7)
- txHash: For transaction-related endpoints (tx_by_hash, tx_raw, tx_receipt)
- txids: For bulk_tx_details endpoint (array of transaction IDs)
- address: For address-related endpoints
- limit: Optional pagination limit for address_history

Network Options

The tool supports both mainnet and testnet:

main: Bitcoin SV mainnet (default)
test: Bitcoin SV testnet

Development

Project Setup

If you want to contribute to the project or run it locally:

Clone the repository:

git clone https://github.com/b-open-io/bsv-mcp.git
cd bsv-mcp

Install dependencies:
```
bun install
# or with npm
npm install
```

Running the Server

bun run index.ts
# or with npm
npm run start

Running Tests

bun test
# or with npm
npm test

Troubleshooting

Make sure you're on the latest version of bun
Make sure the commands can be run directly from your cli
Make sure you're on node v22+

License

This project is licensed under the MIT License - see the LICENSE file for details.

Bitcoin SV MCP Server

⚠️ NOTICE: Experimental Work in Progress
This project is in an early experimental stage. Features may change, and the API is not yet stable. Contributions, feedback, and bug reports are welcome! Feel free to open issues or submit pull requests.

A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework. This library provides wallet, ordinals, and utility functions for BSV blockchain interaction.

Installation Options

Option 1: Hosted Version (FREE - No BSV Required!)

The easiest way to get started! Use our hosted version with OAuth 2.1 authentication:

Configure: Add the MCP server configuration to your IDE
Authenticate: Sign in with your Bitcoin wallet via sigma-auth
Use: Start using BSV features immediately - no BSV needed!

{
  "mcpServers": {
    "bsv-mcp-hosted": {
      "url": "https://bsv-mcp.rohenaz.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

To get your access token, authenticate at https://auth.sigmaidentity.com

Benefits:

✅ No Bitcoin required - we pay for everything
✅ Secure OAuth 2.1 authentication with Bitcoin signatures
✅ Instant setup - no installation needed
✅ Always up-to-date
✅ Global availability via Cloudflare

Option 2: Self-Hosted Installation

Prerequisites

**Use Bun (Optional but recommended)

Installing Bun

macOS (using Homebrew):

brew install oven-sh/bun/bun

macOS/Linux/WSL (using installer script):

curl -fsSL https://bun.sh/install | bash

Windows: Windows users should use WSL (Windows Subsystem for Linux) or Docker to run Bun.

Node.js and npm will also work but may not offer the same performance benefits.

Connecting to MCP Clients

This server implements the Model Context Protocol (MCP), allowing AI assistants to utilize Bitcoin SV functionalities. You can connect this server to various MCP-compatible clients.

MCP Configuration Example

Note: The PRIVATE_KEY_WIF environment variable is now optional. Without it, the server runs in limited mode with educational resources and non-wallet tools available. Wallet and MNEE token operations require a valid private key. You can also set the IDENTITY_KEY_WIF environment variable to enable sigma-protocol signing of ordinals inscriptions for authentication, curation, and web-of-trust.

Claude Code

To use the BSV MCP server with Claude Code:

# Using bunx (recommended)
claude mcp add bsv-mcp "bunx bsv-mcp@latest"

# Or using npx
claude mcp add bsv-mcp "npx bsv-mcp@latest"

To add with environment variables:

claude mcp add bsv-mcp "bunx bsv-mcp@latest" -e PRIVATE_KEY_WIF=your_key -e IDENTITY_KEY_WIF=your_identity_key

For encrypted key storage (recommended):

claude mcp add bsv-mcp "bunx bsv-mcp@latest" -e BSV_MCP_PASSPHRASE="your-secure-passphrase"

Note: The server automatically runs in stdio mode when used with Claude Code CLI.

Cursor

Quick Install: Click the button above to automatically add the BSV MCP server to Cursor! This will install the server with the basic configuration using bunx bsv-mcp@latest.

Manual Setup: To manually configure the BSV MCP server with Cursor:

Install Cursor if you haven't already
Open Cursor and navigate to Settings → Extensions → Model Context Protocol
Click "Add a new global MCP server"
Enter the following configuration in JSON format:

{
  "mcpServers": {
    "Bitcoin SV": {
      "command": "bunx",
      "args": [
        "bsv-mcp@latest"
      ],
      "env": {
        "PRIVATE_KEY_WIF": "<your_private_key_wif>",
        "IDENTITY_KEY_WIF": "<your_identity_key_wif>"
      }
    }
  }
}

Replace <your_private_key_wif> with your actual private key WIF (keep this secure!) If you dont have one you can leave this off for now but you wont be able to use tools that require a wallet. <your_identity_key_wif> is also optional. It will sign 1Sat Ordinals with Sigma protocol using the provided identity key.
Click "Save"

The BSV tools will now be available to Cursor's AI assistant under the "Bitcoin SV" namespace.

Alternative for npm users

If you prefer to use npm instead of Bun:

{
  "mcpServers": {
    "Bitcoin SV": {
      "command": "npx",
      "args": [
        "bsv-mcp@latest"
      ],
      "env": {
        "PRIVATE_KEY_WIF": "<your_private_key_wif>",
        "IDENTITY_KEY_WIF": "<your_identity_key_wif>"
      }
    }
  }
}

Claude for Desktop

To connect this server to Claude for Desktop:

Open Claude for Desktop and go to Claude > Settings > Developer
Click "Edit Config".

Open the Claude configuration json file in your favorite text editor. If you prefer to do it from the cli:

# macOS/Linux
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
code %APPDATA%\Claude\claude_desktop_config.json

Add the BSV MCP server to your configuration:

{
  "mcpServers": {
    "Bitcoin SV": {
      "command": "bun",
      "args": [
        "run", "bsv-mcp@latest"
      ],
      "env": {
        "PRIVATE_KEY_WIF": "<your_private_key_wif>",
        "IDENTITY_KEY_WIF": "<your_identity_key_wif>"
      }
    }
  }
}

Replace <your_private_key_wif> with your actual private key WIF
Save the file and restart Claude for Desktop
The BSV tools will appear when you click the tools icon (hammer) in Claude for Desktop

Alternative for npm users (Claude)

If you prefer to use npm instead of Bun, replace the "command" field with "npx".

VS Code (CLI Method)

If you prefer using the command line, you can add the BSV MCP server to VS Code (which uses the same underlying settings as Cursor) directly:

Using Bun (Recommended):

code --add-mcp '{"name":"Bitcoin SV","command":"bunx","args":["bsv-mcp@latest"],"env":{"PRIVATE_KEY_WIF":"<your_private_key_wif>","IDENTITY_KEY_WIF":"<your_identity_key_wif>"}}'

Using Node.js/npm:

code --add-mcp '{"name":"Bitcoin SV","command":"npx","args":["bsv-mcp@latest"],"env":{"PRIVATE_KEY_WIF":"<your_private_key_wif>","IDENTITY_KEY_WIF":"<your_identity_key_wif>"}}'

Replace <your_private_key_wif> with your actual private key WIF (optional, required for wallet tools).
Replace <your_identity_key_wif> with your identity key WIF (optional, enables Sigma protocol signing).
Ensure the code command is in your system's PATH (it usually is if VS Code was installed normally).

This command adds the server configuration to your VS Code settings.json file under the mcp.servers key.

Available Tools

The toolkit is organized into several categories:

Wallet Tools

Wallet tools provide core BSV wallet functionality:

Tool Name	Description	Example Output
`wallet_getPublicKey`	Retrieves a public key for a specified protocol and key ID	`{"publicKey":"032d0c73eb9270e9e009fd1f9dd77e19cf764fbad5f799560c4e8fd414e40d6fc2"}`
`wallet_createSignature`	Creates a cryptographic signature for the provided data	`{"signature":[144,124,85,193,226,45,140,249,9,177,11,167,33,215,209,38,...]}`
`wallet_verifySignature`	Verifies a cryptographic signature against the provided data	`{"isValid":true}`
`wallet_encryption`	Combined tool for encrypting and decrypting data using the wallet's cryptographic keys. Examples: 1. Encrypt text: `"Encrypt this message: Hello World"` 2. Decrypt data: `"Decrypt this data that was previously encrypted for me"`	Encrypt: `{"ciphertext":[89,32,155,38,125,22,49,226,26,...]}` Decrypt: `{"plaintext":"hello world"}`
`wallet_getAddress`	Returns a BSV address for the current wallet or a derived path	`{"address":"1ExampleBsvAddressXXXXXXXXXXXXXXXXX","status":"ok"}`
`wallet_sendToAddress`	Sends BSV to a specified address (supports BSV or USD amounts)	`{"status":"success","txid":"a1b2c3d4e5f6...","satoshis":1000000}`
`wallet_purchaseListing`	Purchases NFTs or BSV-20/BSV-21 tokens from marketplace listings	`{"status":"success","txid":"a1b2c3d4e5f6...","type":"nft","origin":"abcdef123456..."}`
`wallet_createOrdinals`	Creates and inscribes ordinals on the BSV blockchain	`{"txid":"a1b2c3d4e5f6...","inscriptionAddress":"1ExampleAddress...","contentType":"image/png"}`

BSV Tools

Tools for interacting with the BSV blockchain and network:

Tool Name	Description	Example Output
`bsv_getPrice`	Gets the current BSV price from an exchange API	`Current BSV price: $38.75 USD`
`bsv_decodeTransaction`	Decodes a BSV transaction and returns detailed information	`{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,"inputs":[...],"outputs":[...]}`
`bsv_explore`	Comprehensive blockchain explorer tool accessing WhatsOnChain API endpoints	`{"chain_info":{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"0000000000..."}}`

BSocial Tools

Tools for social interactions on the BSV blockchain (requires wallet):

Tool Name	Description	Example Output
`bsocial_createPost`	Creates a social post on the BSV blockchain using B:// and MAP protocols	`{"success":true,"txid":"a1b2c3d4e5f6...","rawTx":"0100000001..."}`
`bsocial_readPosts`	Reads social posts from the BSV blockchain with filtering options	`Post 1:\n TX ID: a1b2c3...\n Content: Hello BSV!\n Type: text/plain\n Author: 1Example...`

Ordinals Tools

Tools for working with ordinals (NFTs) on BSV:

Tool Name	Description	Example Output
`ordinals_getInscription`	Retrieves detailed information about a specific inscription	`{"id":"a1b2c3d4e5f6...","origin":"a1b2c3d4e5f6...","contentType":"image/png","content":"iVBORw0KGgoAAA..."}`
`ordinals_searchInscriptions`	Searches for inscriptions based on various criteria	`{"results":[{"id":"a1b2c3...","contentType":"image/png","owner":"1Example..."},...]}`
`ordinals_marketListings`	Retrieves market listings for NFTs, BSV-20, and BSV-21 tokens with unified interface	`{"results":[{"txid":"a1b2c3...","price":9990000,"tick":"PEPE","listing":true},...]}`
`ordinals_marketSales`	Gets information about BSV-20 and BSV-21 token market sales	`{"results":[{"txid":"a1b2c3...","price":34710050,"tick":"$BTC","sale":true},...]}`
`ordinals_getTokenByIdOrTicker`	Retrieves details about a specific BSV20 token by ID	`{"tick":"PEPE","max":"21000000","lim":"1000","dec":"2"}`

Utility Tools

General-purpose utility functions:

Tool Name	Description	Example Output
`utils_convertData`	Converts data between different encodings (utf8, hex, base64, binary).

Args:
- data (string, required): The data string to be converted.
- from (string, required): Source encoding format (utf8, hex, base64, or binary).
- to (string, required): Target encoding format (utf8, hex, base64, or binary).
Returns: The converted data as a string.

BAP (Bitcoin Attestation Protocol) Tools

Tools for interacting with BAP identities.

`bap_getId`

Retrieves a Bitcoin Attestation Protocol (BAP) identity profile using an idKey.

Args:
- idKey (string, optional): The Identity Key (Paymail or public key string) to fetch the profile for. If not provided, the tool attempts to use the server's configured identity key (derived from IDENTITY_KEY_WIF or the key file ~/.bsv-mcp/keys.json).
Returns: A JSON string containing the BAP identity data if found, or a message indicating that no identity was found for the given key. Returns an error if the API request fails or the key cannot be derived.

`bap_getCurrentAddress`

Retrieves the current BAP identity's Bitcoin SV address. This address is derived from the server's configured identity key.

Args: None.
Returns: A JSON object containing the address string.

`bap_generate`

Generates a new BAP HD master key (xprv) and saves it to ~/.bsv-mcp/keys.json. This key can be used as a root for deriving multiple BAP identities.

Args: None.
Returns: A JSON object with the generated xprv string and a status message, or an error message if generation/saving fails.

MNEE Tools

Tools for working with MNEE tokens:

Tool Name	Description	Example Output
`mnee_getBalance`	Retrieves the current MNEE token balance for the wallet	`{"balance": {"amount": 2900, "decimalAmount": 0.029}}`
`mnee_sendMnee`	Send MNEE tokens to a specified address. Supports both MNEE and USD amounts	`{"success": true, "txid": "d1ce853934964e6c1fe9f44c918a824f175c6ab466b966f49ebc0682a8318895", "rawtx": "0100000002a0be40d8942015f1...", "mneeAmount": 0.01, "usdAmount": "$0.01", "recipient": "15mNxEkyKJXPD8amic6oLUjS45zBKQQoLu"}`
`mnee_parseTx`	Parse an MNEE transaction to get detailed information about its operations and amounts. All amounts are in atomic units with 5 decimal precision (e.g. 1000 atomic units = 0.01 MNEE)	`{"txid": "d1ce853934964e6c1fe9f44c918a824f175c6ab466b966f49ebc0682a8318895", "environment": "production", "type": "transfer", "inputs": [{"address": "18izL7Wtm2fx3ALoRY3MkY2VFSMjArP62D", "amount": 2900}], "outputs": [{"address": "15mNxEkyKJXPD8amic6oLUjS45zBKQQoLu", "amount": 1000}, {"address": "19Vq2TV8aVhFNLQkhDMdnEQ7zT96x6F3PK", "amount": 100}, {"address": "18izL7Wtm2fx3ALoRY3MkY2VFSMjArP62D", "amount": 1800}]}`

Using the Tools with MCP

Once connected, you can use natural language to interact with Bitcoin SV through your AI assistant. Here are some example prompts:

Wallet Operations

"Get my Bitcoin SV address"
"Send 0.01 BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
"Send $5 USD worth of BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
"Send 0.01 MNEE to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
"Check my MNEE balance"
"Parse this MNEE transaction: txid"
"Encrypt this message using my wallet's keys"
"Decrypt this data that was previously encrypted for me"
"Purchase this NFT listing: txid_vout"
"Purchase this BSV-20 token listing: txid_vout"

Ordinals (NFTs)

"Show me information about the NFT with outpoint 6a89047af2cfac96da17d51ae8eb62c5f1d982be2bc4ba0d0cd2084b7ffed325_0"
"Search for Pixel Zoide NFTs"
"Show me the current marketplace listings for BSV NFTs"
"Show me BSV-20 token listings for ticker PEPE"
"Get recent BSV-20 token sales"

Collection Minting

The BSV MCP server provides a two-step process for minting ordinal collections from folders of images:

Gather Collection Info (Pre-flight check)
- "Analyze the folder /path/to/my/nft-images for collection minting"
- "Check if I can mint a collection from ./my-art-folder"
This step will:
- Validate all images in the folder
- Check your wallet balance
- Estimate total costs
- Suggest collection metadata
- Report any issues before minting
Mint Collection (Create the collection)
- "Mint a collection called 'My Art Collection' from /path/to/images with description 'Amazing digital art'"
- "Create an NFT collection from ./my-art-folder with traits: background=[red,blue,green], style=[vintage,modern]"
- "Mint collection with rarity labels: common=60%, rare=30%, legendary=10%"

Blockchain Operations

"What is the current BSV price?"
"Decode this BSV transaction: (transaction hex or ID)"
"Get the latest Bitcoin SV chain information"
"Show me block details for height 800000"
"Explore transaction history for address 1ExampleBsvAddressXXXX"
"Check unspent outputs (UTXOs) for my wallet address"
"Get details for transaction with hash a1b2c3d4e5f6..."

Data Conversion

"Convert 'Hello World' from UTF-8 to hex format"

"Create a post saying 'Hello BSV World!' on the blockchain"
"Post a markdown message: # My First On-Chain Post\n\nThis is bold and italic text"
"Read the latest social posts from the blockchain"
"Read posts by BAP identity 1SomeIdentityKey..."
"Get the post with transaction ID a1b2c3d4e5f6..."
"Show me replies to post txid a1b2c3d4e5f6..."

MCP Prompts and Resources

Available Prompts

The server provides the following educational prompts that can be accessed directly via the MCP protocol:

Ordinals Prompt

Identifier: bitcoin_sv_ordinals
Description: Comprehensive information about Bitcoin SV ordinals, including what they are, how they work, and how to use them.
Usage: Ask the assistant about "Bitcoin SV ordinals" or "1Sat Ordinals" to access this information.

BSV SDK Prompts

A collection of prompts providing detailed information about the Bitcoin SV SDK:

Overview
- Identifier: bitcoin_sv_sdk_overview
- Description: General overview of the Bitcoin SV SDK, including its purpose and main components.
- Usage: "Tell me about the BSV SDK" or "What is the Bitcoin SV SDK?"
Wallet Operations
- Identifier: bitcoin_sv_sdk_wallet
- Description: Information about wallet operations in the BSV SDK.
- Usage: "How do wallet operations work in the BSV SDK?"
Transaction Building
- Identifier: bitcoin_sv_sdk_transaction
- Description: Details about transaction creation and manipulation.
- Usage: "Explain BSV SDK transaction building" or "How do I create transactions with BSV SDK?"
Authentication
- Identifier: bitcoin_sv_sdk_auth
- Description: Authentication and identity protocols in BSV SDK.
- Usage: "How does authentication work with BSV SDK?"
Cryptography
- Identifier: bitcoin_sv_sdk_cryptography
- Description: Signing, encryption, and verification functionality.
- Usage: "Explain BSV SDK cryptography features"
Scripting
- Identifier: bitcoin_sv_sdk_script
- Description: Bitcoin scripting and contract capabilities.
- Usage: "How do I work with Bitcoin scripts using the BSV SDK?"
Primitives
- Identifier: bitcoin_sv_sdk_primitives
- Description: Core data types and structures in the BSV SDK.
- Usage: "What primitives are available in the BSV SDK?"

Available Resources

The server also provides access to Bitcoin Request for Comments (BRC) specifications and documentation:

Changelog Resource

Identifier: bsv-mcp-changelog
Description: Version history and changelog for the BSV MCP server.
Usage: "Show me the BSV MCP changelog" or "What's new in the latest version?"

BRC Resources

BRCs Overview
- Identifier: brcs_readme
- Description: Overview of all Bitcoin SV protocol specifications in the BRCs repository.
- Usage: "Show me the Bitcoin SV BRCs overview"
BRCs Summary
- Identifier: brcs_summary
- Description: Table of contents for all Bitcoin SV BRCs.
- Usage: "Give me a summary of Bitcoin SV BRCs"
Specific BRC Specifications
- Identifier: brc_spec
- Description: Access specific BRC specifications by category and number.
- Usage: "Show me BRC 8 on Transaction Envelopes" or "What does BRC 1 specify?"

BRC Categories

The BRC specifications are organized into the following categories:

Wallet
Transactions
Scripts
Tokens
Overlays
Payments
Peer-to-Peer
Key Derivation
Outpoints
Opinions
State Machines
Apps

Using Prompts and Resources

AI models can use these prompts and resources to provide more accurate and detailed responses about Bitcoin SV technologies. As a user, you can:

Ask about a specific topic: "Tell me about Bitcoin SV ordinals" or "Explain BSV SDK transaction building"
Request specific BRC details: "What does BRC 8 specify?" or "Show me the BRC on Transaction Creation"
Get general overviews: "What is the BSV SDK?" or "Show me a summary of all BRCs"

These prompts and resources enhance the AI's knowledge base, enabling more technical and accurate responses even for complex Bitcoin SV topics.

How MCP Works

When you interact with an MCP-enabled AI assistant:

The AI analyzes your request and decides which tools to use
With your approval, it calls the appropriate BSV MCP tool
The server executes the requested operation on the Bitcoin SV blockchain
The results are returned to the AI assistant
The assistant presents the information in a natural, conversational way

Key Management & Security

Encrypted Key Storage (Recommended)

BSV MCP now supports encrypted key storage using bitcoin-backup for enhanced security:

Set a passphrase (minimum 8 characters):

export BSV_MCP_PASSPHRASE="your-secure-passphrase"

Automatic migration: Keys will be automatically encrypted when a passphrase is provided

Manual migration: Use the migration script:

BSV_MCP_PASSPHRASE="your-passphrase" bun run scripts/migrate-keys.ts

File locations:
- Encrypted keys: ~/.bsv-mcp/keys.bep
- Legacy keys: ~/.bsv-mcp/keys.json (deprecated)
- Automatic backup: ~/.bsv-mcp/keys.bep.backup

Security Best Practices

Use encrypted storage: Always set BSV_MCP_PASSPHRASE for production use
Strong passphrases: Use 12+ characters with mixed case, numbers, and symbols
Backup your keys: Keep secure backups of both keys and passphrase
File permissions: Key files are automatically created with restricted permissions (0600)

Environment Variables for Key Management

Variable	Description	Default
`BSV_MCP_PASSPHRASE`	Passphrase for encrypted key storage	None
`BSV_MCP_AUTO_MIGRATE`	Automatically migrate legacy keys	`false`
`BSV_MCP_KEEP_LEGACY`	Keep unencrypted keys after migration	`false`

Customization Options

The BSV MCP server can be customized using environment variables to enable or disable specific components:

Component Configuration

Environment Variable	Default	Description
`DISABLE_PROMPTS`	`false`	Set to `true` to disable all educational prompts
`DISABLE_RESOURCES`	`false`	Set to `true` to disable all resources (BRCs, changelog)
`DISABLE_TOOLS`	`false`	Set to `true` to disable all tools

Tool-Specific Configuration

Environment Variable	Default	Description
`DISABLE_WALLET_TOOLS`	`false`	Set to `true` to disable Bitcoin wallet tools
`DISABLE_MNEE_TOOLS`	`false`	Set to `true` to disable MNEE token tools
`DISABLE_BSV_TOOLS`	`false`	Set to `true` to disable BSV blockchain tools
`DISABLE_ORDINALS_TOOLS`	`false`	Set to `true` to disable Ordinals/NFT tools
`DISABLE_UTILS_TOOLS`	`false`	Set to `true` to disable utility tools
`IDENTITY_KEY_WIF`	`not set`	Optional WIF for identity key; if set, ordinals inscriptions will be signed with sigma-protocol for authentication, curation, and web-of-trust.
`DISABLE_BROADCASTING`	`false`	Set to `true` to disable transaction broadcasting; returns raw transaction hex instead - useful for testing and transaction review before broadcasting

Droplet API Configuration

The BSV MCP server supports running in Droplet API mode, which allows operation without local private keys by using a remote faucet service:

Environment Variable	Default	Description
`USE_DROPLET_API`	`false`	Set to `true` to enable Droplet API mode for remote wallet operations
`DROPLET_API_URL`	`http://localhost:4000`	Base URL for the Droplet faucet API service
`DROPLET_FAUCET_NAME`	`not set`	Name of the faucet to use (required when `USE_DROPLET_API` is true)
`TRANSPORT`	`stdio`	MCP transport mode (stdio/http) - automatically set to stdio for Claude Code compatibility

Droplet API Mode

When USE_DROPLET_API=true is set, the server operates in remote mode:

No Local Keys Required: The server doesn't need PRIVATE_KEY_WIF or local key files
Remote Wallet Operations: Transactions are funded and broadcast through the Droplet API
BSM Authentication: Uses Bitcoin Signed Message (BSM) authentication for secure API communication
Automatic Funding: The faucet automatically provides UTXOs for transactions
Seamless Integration: All existing wallet tools work transparently with the remote service

Example Droplet Configuration

# Enable Droplet API mode
USE_DROPLET_API=true
DROPLET_API_URL=https://your-droplet-service.com
DROPLET_FAUCET_NAME=your-faucet-name
TRANSPORT=stdio

This mode is particularly useful for:

Development and Testing: No need to manage local private keys
Educational Environments: Safe experimentation without real funds
Shared Environments: Multiple users can use the same faucet service
Simplified Deployment: Reduced security concerns for demonstration purposes

Examples

Run with only educational resources and prompts, no tools:

DISABLE_TOOLS=true bunx bsv-mcp@latest

Run with only BSV tools, no wallet or other functionality:

DISABLE_PROMPTS=true DISABLE_RESOURCES=true DISABLE_WALLET_TOOLS=true DISABLE_MNEE_TOOLS=true DISABLE_ORDINALS_TOOLS=true DISABLE_UTILS_TOOLS=true bunx bsv-mcp@latest

Use all tools except wallet operations:

DISABLE_WALLET_TOOLS=true bunx bsv-mcp@latest

Create transactions without broadcasting them (dry-run mode):

DISABLE_BROADCASTING=true bunx bsv-mcp@latest

Troubleshooting

If you're having issues with the BSV MCP server:

Connection Issues

Make sure Bun or Node.js is installed on your system
Verify your WIF private key is correctly set in the environment
Check that your client supports MCP and is properly configured
Look for error messages in the client's console output

Keeping Bun Up to Date

It's important to keep Bun updated to the latest version to ensure compatibility:

# Update Bun to the latest version
bun upgrade

To verify your current Bun version:

bun --version

Logging and Debugging

For Claude for Desktop, check the logs at:

# macOS/Linux
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Windows
type %APPDATA%\Claude\Logs\mcp*.log

For Cursor, check the Cursor MCP logs in Settings → Extensions → Model Context Protocol.

Recent Updates

Transaction Broadcast Control: Added DISABLE_BROADCASTING environment variable to prevent transactions from being broadcast to the network
Blockchain Explorer: Added bsv_explore tool for WhatsOnChain API access with mainnet/testnet support
Unified Tools: Merged wallet_encrypt/wallet_decrypt into single wallet_encryption tool
Enhanced Marketplace: Support for NFTs, BSV-20/21 tokens in listings, sales and purchases
Performance: Added price caching and optimized API endpoint structure
Improved Validation: Better error handling for private keys and parameters

Bitcoin SV Blockchain Explorer

Available Endpoints

The tool supports the following endpoint categories and specific endpoints:

Chain Data

Endpoint	Description	Required Parameters	Example Response
`chain_info`	Network statistics, difficulty, and chain work	None	`{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"0000000000..."}`
`chain_tips`	Current chain tips including heights and states	None	`[{"height":826458,"hash":"000000000000...","branchlen":0,"status":"active"}]`
`circulating_supply`	Current BSV circulating supply	None	`{"bsv":21000000}`
`peer_info`	Connected peer statistics	None	`[{"addr":"1.2.3.4:8333","services":"000000000000...","lastsend":1621234567}]`

Block Data

Endpoint	Description	Required Parameters	Example Response
`block_by_hash`	Complete block data via hash	`blockHash`	`{"hash":"000000000000...","confirmations":1000,"size":1000000,...}`
`block_by_height`	Complete block data via height	`blockHeight`	`{"hash":"000000000000...","confirmations":1000,"size":1000000,...}`
`tag_count_by_height`	Stats on tag count for a specific block	`blockHeight`	`{"tags":{"amp":3,"bitkey":5,"metanet":12,"planaria":7,"b":120}}`
`block_headers`	Retrieves the last 10 block headers	None	`[{"hash":"000000000000...","height":826458,"version":536870912,...},...]`
`block_pages`	Retrieves pages of transaction IDs for large blocks	`blockHash`, optional: `pageNumber`	`["tx1hash","tx2hash","tx3hash",...]`

Stats Data

Endpoint	Description	Required Parameters	Example Response
`block_stats_by_height`	Block statistics for a specific height	`blockHeight`	`{"size":123456,"txCount":512,"outputTotal":54.12345678,"outputTotalUsd":2345.67,...}`
`block_miner_stats`	Block mining statistics for a time period	optional: `days` (default 7)	`{"blocks":{"miner1":412,"miner2":208,...},"total":1008}`
`miner_summary_stats`	Summary of mining statistics	optional: `days` (default 7)	`{"totalBlocks":1008,"totalFees":1.23456789,"totalFeesUsd":53.67,...}`

Transaction Data

Endpoint	Description	Required Parameters	Example Response
`tx_by_hash`	Detailed transaction data	`txHash`	`{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,...}`
`tx_raw`	Raw transaction hex data	`txHash`	`"01000000012345abcdef..."`
`tx_receipt`	Transaction receipt	`txHash`	`{"blockHash":"000000000000...","blockHeight":800000,"confirmations":26458}`
`bulk_tx_details`	Retrieve multiple transactions in one request	`txids` (array)	`[{"txid":"a1b2c3d4e5f6...","version":1,...}, {"txid":"b2c3d4e5f6a7...","version":1,...}]`

Address Data

Endpoint	Description	Required Parameters	Example Response
`address_history`	Transaction history for address	`address`, optional: `limit`	`[{"tx_hash":"a1b2c3d4e5f6...","height":800000},...]`
`address_utxos`	Unspent outputs for address	`address`	`[{"tx_hash":"a1b2c3d4e5f6...","tx_pos":0,"value":100000},...]`

Network

Endpoint	Description	Required Parameters	Example Response
`health`	API health check	None	`{"status":"synced"}`

Usage Examples

The bsv_explore tool can be used with natural language prompts like:

"Get the current Bitcoin SV blockchain information"
"Show me block #800000 details"
"Get tag count statistics for block #800000"
"Fetch transaction history for address 1ExampleBsvAddressXXXXXXXX"
"Get unspent outputs for my wallet address"
"Check transaction details for txid a1b2c3d4e5f6..."
"What is the current BSV circulating supply?"
"Show me the latest block headers"
"Get transaction IDs for page 2 of a large block"
"Show me block statistics for height 800000"
"What are the mining statistics for the last 14 days?"
"Get a summary of mining activity over the past 30 days"
"Retrieve details for multiple transactions in a single query"

Under the hood, the tool accepts parameters to specify which data to retrieve:

endpoint: The specific WhatsOnChain endpoint to query (e.g., chain_info, tx_by_hash)
network: The BSV network to use (main or test)
Additional parameters as required by the specific endpoint:
- blockHash: For block_by_hash and block_pages endpoints
- blockHeight: For block_by_height, tag_count_by_height, and block_stats_by_height endpoints
- pageNumber: For block_pages endpoint (pagination)
- days: For block_miner_stats and miner_summary_stats endpoints (defaults to 7)
- txHash: For transaction-related endpoints (tx_by_hash, tx_raw, tx_receipt)
- txids: For bulk_tx_details endpoint (array of transaction IDs)
- address: For address-related endpoints
- limit: Optional pagination limit for address_history

Network Options

The tool supports both mainnet and testnet:

main: Bitcoin SV mainnet (default)
test: Bitcoin SV testnet

Development

Project Setup

If you want to contribute to the project or run it locally:

Clone the repository:

git clone https://github.com/b-open-io/bsv-mcp.git
cd bsv-mcp

Install dependencies:
```
bun install
# or with npm
npm install
```

Running the Server

bun run index.ts
# or with npm
npm run start

Running Tests

bun test
# or with npm
npm test

Troubleshooting

Make sure you're on the latest version of bun
Make sure the commands can be run directly from your cli
Make sure you're on node v22+

License

This project is licensed under the MIT License - see the LICENSE file for details.

Bitcoin SV MCP Server

Bitcoin SV MCP Server

Installation Options

Option 1: Hosted Version (FREE - No BSV Required!)

Option 2: Self-Hosted Installation

Prerequisites

Installing Bun

Connecting to MCP Clients

Claude Code

Cursor

Alternative for npm users

Claude for Desktop

Alternative for npm users (Claude)

VS Code (CLI Method)

Available Tools

Wallet Tools

BSV Tools

BSocial Tools

Ordinals Tools

Utility Tools

BAP (Bitcoin Attestation Protocol) Tools

bap_getId

bap_getCurrentAddress

bap_generate

MNEE Tools

Using the Tools with MCP

Wallet Operations

Ordinals (NFTs)

Collection Minting

Blockchain Operations

Data Conversion

Social Posts

MCP Prompts and Resources

Available Prompts

Ordinals Prompt

BSV SDK Prompts

Available Resources

Changelog Resource

BRC Resources

BRC Categories

Using Prompts and Resources

How MCP Works

Key Management & Security

Encrypted Key Storage (Recommended)

Security Best Practices

Environment Variables for Key Management

Customization Options

Component Configuration

Tool-Specific Configuration

Droplet API Configuration

Droplet API Mode

Example Droplet Configuration

Examples

Troubleshooting

Connection Issues

Keeping Bun Up to Date

Logging and Debugging

Recent Updates

Bitcoin SV Blockchain Explorer

Available Endpoints

Chain Data

Block Data

Stats Data

Transaction Data

Address Data

Network

Usage Examples

Network Options

Development

Project Setup

Running the Server

Running Tests

Troubleshooting

License

Bitcoin SV MCP Server

Installation Options

Option 1: Hosted Version (FREE - No BSV Required!)

Option 2: Self-Hosted Installation

Prerequisites

Installing Bun

`bap_getId`

`bap_getCurrentAddress`

`bap_generate`

`bap_getId`

`bap_getCurrentAddress`

`bap_generate`