Bitcoin SV MCP Server

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 and Setup

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):

macOS/Linux/WSL (using installer script):

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.

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.

Cursor

To use the BSV MCP server with Cursor:

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

5. 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.
6. 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:

Claude for Desktop

To connect this server to Claude for Desktop:

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

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

3. 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>" } } } }
4. Replace <your_private_key_wif> with your actual private key WIF
5. Save the file and restart Claude for Desktop
6. 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".

Available Tools

The toolkit is organized into several categories:

Wallet Tools

Wallet tools provide core BSV wallet functionality:

BSV Tools

Tools for interacting with the BSV blockchain and network:

Ordinals Tools

Tools for working with ordinals (NFTs) on BSV:

Utility Tools

General-purpose utility functions:

MNEE Tools

Tools for working with MNEE tokens:

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"

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"

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:

1. Ask about a specific topic: "Tell me about Bitcoin SV ordinals" or "Explain BSV SDK transaction building"
2. Request specific BRC details: "What does BRC 8 specify?" or "Show me the BRC on Transaction Creation"
3. 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:

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

Customization Options

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

Component Configuration

Tool-Specific Configuration

Examples

Run with only educational resources and prompts, no tools:

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

Use all tools except wallet operations:

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

Troubleshooting

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

Connection Issues

1. Make sure Bun or Node.js is installed on your system
2. Verify your WIF private key is correctly set in the environment
3. Check that your client supports MCP and is properly configured
4. 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:

To verify your current Bun version:

Logging and Debugging

For Claude for Desktop, check the logs at:

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

Block Data

Stats Data

Transaction Data

Address Data

Network

Usage Examples

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

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:

1. Clone the repository:
   git clone https://github.com/b-open-io/bsv-mcp.git cd bsv-mcp
2. Install dependencies:
   bun install # or with npm npm install

Running the Server

Running Tests

License

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