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:

1. Configure: Add the MCP server configuration to your IDE
2. Authenticate: Sign in with your Bitcoin wallet via sigma-auth
3. 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.

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:

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:

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

1. 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.

2. 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:

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:

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

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

1. 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>"
         }
       }
     }
   }
   

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

---