Bitcoin SV Wallet MCP server for AI agents

The Bitcoin SV MCP Server is a collection of Bitcoin SV (BSV) tools that enables interaction with the BSV blockchain through the Model Context Protocol (MCP) framework. It provides wallet capabilities, ordinals functionality, and utility functions for seamless blockchain interaction.

Installation

To install the dependencies, run:

bun install

External Dependencies

For full functionality, especially ordinal listing purchase features, you'll need:

# For ordinal listing purchase functionality
js-1sat-ord

Running the Server

Start the MCP server with:

bun run index.ts

Connecting to MCP Clients

Cursor

To use with Cursor:

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

{
  "Bitcoin SV": {
    "command": "env",
    "args": [
      "PRIVATE_KEY_WIF=<your_private_key_wif>",
      "bun",
      "run",
      "<path_to_project>/index.ts"
    ]
  }
}

Replace <your_private_key_wif> with your actual private key WIF
Replace <path_to_project> with the full path to your repository
Click "Save"

Claude for Desktop

To connect to Claude for Desktop:

Ensure you have Claude for Desktop installed
Clone this repository and run bun install
Open your Claude configuration file:

# 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": "env",
      "args": [
        "PRIVATE_KEY_WIF=<your_private_key_wif>",
        "bun",
        "run",
        "<path_to_project>/index.ts"
      ]
    }
  }
}

Replace placeholders with actual values
Save the file and restart Claude for Desktop

Generic MCP Client Integration

For other MCP clients that support JSON configuration:

{
  "Bitcoin SV": {
    "command": "env",
    "args": [
      "PRIVATE_KEY_WIF=<your_private_key_wif>",
      "bun",
      "run",
      "<path_to_project>/index.ts"
    ]
  }
}

If running the server directly:

# Set environment variable first
export PRIVATE_KEY_WIF=<your_private_key_wif>

# Then run the server
bun run index.ts

Available Tools

Wallet Tools

These tools provide core BSV wallet functionality:

wallet_getPublicKey: Retrieves a public key for a specified protocol and key ID
wallet_createSignature: Creates a cryptographic signature for the provided data
wallet_verifySignature: Verifies a cryptographic signature against the provided data
wallet_encryption: Combined tool for encrypting and decrypting data using the wallet's cryptographic keys
wallet_getAddress: Returns a BSV address for the current wallet or a derived path
wallet_sendToAddress: Sends BSV to a specified address (supports BSV or USD amounts)
wallet_purchaseListing: Purchases NFTs or BSV-20/BSV-21 tokens from marketplace listings
wallet_createOrdinals: Creates and inscribes ordinals on the BSV blockchain

BSV Tools

Tools for interacting with the BSV blockchain and network:

bsv_getPrice: Gets the current BSV price from an exchange API
bsv_decodeTransaction: Decodes a BSV transaction and returns detailed information
bsv_explore: Comprehensive blockchain explorer tool accessing WhatsOnChain API endpoints

Ordinals Tools

Tools for working with ordinals (NFTs) on BSV:

ordinals_getInscription: Retrieves detailed information about a specific inscription
ordinals_searchInscriptions: Searches for inscriptions based on various criteria
ordinals_marketListings: Retrieves market listings for NFTs, BSV-20, and BSV-21 tokens
ordinals_marketSales: Gets information about BSV-20 and BSV-21 token market sales
ordinals_getTokenByIdOrTicker: Retrieves details about a specific BSV20 token by ID

Utility Tools

General-purpose utility functions:

utils_convertData: Converts data between different encoding formats (utf8, hex, base64, binary)

Using the Tools with MCP

Once connected, you can use natural language to interact with Bitcoin SV through your AI assistant:

Wallet Operations

"Get my Bitcoin SV address"
"Send 0.01 BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
"Send $5 USD worth of BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
"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"

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

Troubleshooting

If you're having issues connecting to the server:

Ensure the package dependencies are properly installed: bun install
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

For Claude for Desktop, check the logs at:

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

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

Bitcoin SV Blockchain Explorer

The bsv_explore tool provides comprehensive access to the Bitcoin SV blockchain through the WhatsOnChain API.

Available Endpoints

The tool supports the following endpoint categories:

Chain Data

chain_info: Network statistics, 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
block_by_height: Complete block data via height
tag_count_by_height: Stats on tag count for a specific block
block_headers: Retrieves the last 10 block headers
block_pages: Retrieves pages of transaction IDs for large blocks

Stats Data

block_stats_by_height: Block statistics for a specific height
block_miner_stats: Block mining statistics for a time period
miner_summary_stats: Summary of mining statistics

Transaction Data

tx_by_hash: Detailed transaction data
tx_raw: Raw transaction hex data
tx_receipt: Transaction receipt
bulk_tx_details: Retrieve multiple transactions in one request

Address Data

address_history: Transaction history for address
address_utxos: Unspent outputs for address

Network

health: API health check

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?"

Network Options

The tool supports both:

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "Bitcoin-SV" '{"command":"env","args":["PRIVATE_KEY_WIF=<your_private_key_wif>","bun","run","<path_to_project>/index.ts"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "Bitcoin SV": {
            "command": "env",
            "args": [
                "PRIVATE_KEY_WIF=<your_private_key_wif>",
                "bun",
                "run",
                "<path_to_project>/index.ts"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "Bitcoin SV": {
            "command": "env",
            "args": [
                "PRIVATE_KEY_WIF=<your_private_key_wif>",
                "bun",
                "run",
                "<path_to_project>/index.ts"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect