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

To install dependencies:

bun install

For global installation (recommended for MCP client integration):

# Install globally with bun
bun install -g bsv-mcp

# Or with npm
npm install -g bsv-mcp

External Dependencies

For full functionality of all tools, the following additional dependencies are installed:

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

Running the Server

Start the MCP server:

# If installed locally
bun run index.ts

# If installed globally
bunx bsv-mcp

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.

Cursor

To use the BSV MCP server with Cursor:

1. Install Cursor if you haven't already
2. Install this package globally: bun install -g bsv-mcp
3. Open Cursor and navigate to Settings → Extensions → Model Context Protocol
4. Click "Add a new global MCP server"
5. Enter the following configuration in JSON format:

{
  "Bitcoin SV": {
    "command": "env",
    "args": [
      "PRIVATE_KEY_WIF=<your_private_key_wif>",
      "bunx",
      "bsv-mcp"
    ]
  }
}

6. Replace <your_private_key_wif> with your actual private key WIF (keep this secure!)
7. Click "Save"

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

Claude for Desktop

To connect this server to Claude for Desktop:

1. Ensure you have Claude for Desktop installed and updated to the latest version
2. Install this package globally: bun install -g bsv-mcp
3. Open your Claude for Desktop configuration file:

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

4. Add the BSV MCP server to your configuration (create the file if it doesn't exist):

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

5. Replace <your_private_key_wif> with your actual private key WIF
6. Save the file and restart Claude for Desktop
7. The BSV tools will appear when you click the tools icon (hammer) in 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>",
      "bunx",
      "bsv-mcp"
    ]
  }
}

If running the server directly:

# Set environment variable first
export PRIVATE_KEY_WIF=<your_private_key_wif>

# Then run the server
bunx bsv-mcp

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:

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"

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"

Blockchain Operations

• "What is the current BSV price?"
• "Decode this BSV transaction: (transaction hex or ID)"

Data Conversion

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

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

Troubleshooting

If you're having issues connecting to the server:

1. Ensure the package is properly installed: bun install -g bsv-mcp
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

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.

Development

This project was created using bun init in bun v1.2.9. Bun is a fast all-in-one JavaScript runtime.

Package Configuration

To ensure the package can be run with bunx bsv-mcp, make sure your package.json includes:

{
  "name": "bsv-mcp",
  "bin": {
    "bsv-mcp": "./index.ts"
  },
  "type": "module"
  // ...other configuration
}

Running Tests

bun test

License

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