Provides wallet functionality, BSV blockchain interaction, ordinals/NFT management, and utility tools for Bitcoin SV. Capabilities include retrieving addresses, sending transactions, purchasing NFTs, getting price information, working with ordinals, and managing BSV20 tokens.
Uses Bun as the JavaScript runtime for the MCP server, enabling fast execution of the Bitcoin SV tools and capabilities.
⚠️ 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.
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.
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.
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_WIFenvironment 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 theIDENTITY_KEY_WIFenvironment variable to enable sigma-protocol signing of ordinals inscriptions for authentication, curation, and web-of-trust.
To use the BSV MCP server with Cursor:
<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.The BSV tools will now be available to Cursor's AI assistant under the "Bitcoin SV" namespace.
If you prefer to use npm instead of Bun:
To connect this server to Claude for Desktop:
Open the Claude configuration json file in your favorite text editor. If you prefer to do it from the cli:
<your_private_key_wif> with your actual private key WIFIf you prefer to use npm instead of Bun, replace the "command" field with "npx".
The toolkit is organized into several categories:
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"} |
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..."}} |
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"} |
General-purpose utility functions:
| Tool Name | Description | Example Output |
|---|---|---|
utils_convertData | Converts data between different encoding formats (utf8, hex, base64, binary).Parameters:- data (required): The string to convert- from (required): Source encoding format (utf8, hex, base64, or binary)- to (required): Target encoding format (utf8, hex, base64, or binary)Examples:- UTF-8 to hex: {"data": "hello world", "from": "utf8", "to": "hex"} → 68656c6c6f20776f726c64- UTF-8 to base64: {"data": "Hello World", "from": "utf8", "to": "base64"} → SGVsbG8gV29ybGQ=- base64 to UTF-8: {"data": "SGVsbG8gV29ybGQ=", "from": "base64", "to": "utf8"} → Hello World- hex to base64: {"data": "68656c6c6f20776f726c64", "from": "hex", "to": "base64"} → aGVsbG8gd29ybGQ=Notes:- All parameters are required- The tool returns the converted data as a string- For binary conversion, data is represented as an array of byte values | "SGVsbG8gV29ybGQ=" (UTF-8 "Hello World" converted to base64) |
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}]} |
Once connected, you can use natural language to interact with Bitcoin SV through your AI assistant. Here are some example prompts:
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.
The server provides the following educational prompts that can be accessed directly via the MCP protocol:
bitcoin_sv_ordinalsA collection of prompts providing detailed information about the Bitcoin SV SDK:
bitcoin_sv_sdk_overviewbitcoin_sv_sdk_walletbitcoin_sv_sdk_transactionbitcoin_sv_sdk_authbitcoin_sv_sdk_cryptographybitcoin_sv_sdk_scriptbitcoin_sv_sdk_primitivesThe server also provides access to Bitcoin Request for Comments (BRC) specifications and documentation:
bsv-mcp-changelogbrcs_readmebrcs_summarybrc_specThe BRC specifications are organized into the following categories:
AI models can use these prompts and resources to provide more accurate and detailed responses about Bitcoin SV technologies. As a user, you can:
These prompts and resources enhance the AI's knowledge base, enabling more technical and accurate responses even for complex Bitcoin SV topics.
When you interact with an MCP-enabled AI assistant:
The BSV MCP server can be customized using environment variables to enable or disable specific components:
| 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 |
| 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 |
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):
If you're having issues with the BSV MCP server:
It's important to keep Bun updated to the latest version to ensure compatibility:
To verify your current Bun version:
For Claude for Desktop, check the logs at:
For Cursor, check the Cursor MCP logs in Settings → Extensions → Model Context Protocol.
DISABLE_BROADCASTING environment variable to prevent transactions from being broadcast to the networkbsv_explore tool for WhatsOnChain API access with mainnet/testnet supportwallet_encrypt/wallet_decrypt into single wallet_encryption toolThe 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.
The tool supports the following endpoint categories and specific endpoints:
| 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}] |
| 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",...] |
| 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,...} |
| 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,...}] |
| 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},...] |
| Endpoint | Description | Required Parameters | Example Response |
|---|---|---|---|
health | API health check | None | {"status":"synced"} |
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)blockHash: For block_by_hash and block_pages endpointsblockHeight: For block_by_height, tag_count_by_height, and block_stats_by_height endpointspageNumber: 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 endpointslimit: Optional pagination limit for address_historyThe tool supports both mainnet and testnet:
main: Bitcoin SV mainnet (default)test: Bitcoin SV testnetIf you want to contribute to the project or run it locally:
This project is licensed under the MIT License - see the LICENSE file for details.
You must be authenticated.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A collection of Bitcoin SV tools for the Model Context Protocol that enables AI assistants to interact with the BSV blockchain through wallet operations, ordinals (NFTs), and various blockchain utilities.