Bitcoin SV MCP Server

⚠️ ATTENTION: Preliminary Implementation Stage
This software is presently undergoing early experimental development. Functionality is subject to evolution, and the Application Programming Interface (API) lacks final stability guarantees. Community contributions, operational feedback, and defect reports are highly encouraged! Please feel liberated to file issues or submit proposed modifications via pull requests.

This repository houses a collection of Bitcoin SV (BSV) service modules engineered for integration with the Model Context Protocol (MCP) framework. This library furnishes essential capabilities for wallet management, ordinal asset handling, and utility functions necessary for seamless interaction with the BSV blockchain ecosystem.

Deployment and Initial Configuration

Preferred Execution with Bun

This software stack is optimized for Bun, recognized as a rapid JavaScript environment and package supervisor. While Bun is suggested for peak operational efficiency, compatibility with Node.js and npm environments is maintained due to Bun's commitment to backward compatibility.

Installing Bun

macOS (Utilizing Homebrew):

brew install oven-sh/bun/bun

macOS/Linux/WSL (Via Installer Script):

curl -fsSL https://bun.sh/install | bash

Windows: Windows operators should employ WSL (Windows Subsystem for Linux) or containerization solutions (Docker) to execute Bun.

Node.js and npm will serve as functional fallbacks, though potential performance advantages offered by Bun might be diminished.

Establishing Connection with MCP Clients

This server adheres to the specifications of the Model Context Protocol (MCP), thereby enabling AI agents to leverage sophisticated Bitcoin SV operations. You may link this service instance to any client infrastructure that supports MCP standards.

Important Note: The PRIVATE_KEY_WIF environment parameter is now optional. Absence of this key restricts the server to educational resources and non-custodial utility operations. Full wallet functionality and MNEE token transaction capabilities mandate a correctly provisioned private key. Optionally, setting the IDENTITY_KEY_WIF environment variable activates sigma-protocol signing for ordinal inscriptions, supporting identity verification, curation streams, and web-of-trust mechanisms.

Integrating with Cursor

To leverage the BSV MCP service within Cursor:

1. Ensure Cursor is installed on your system.
2. In Cursor, navigate to Settings → Extensions → Model Context Protocol.
3. Select "Add a new global MCP server".
4. Input the subsequent configuration structure 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. Substitute <your_private_key_wif> with your sensitive WIF private key (handle with extreme security!). Omission is permitted for non-custodial use cases. <your_identity_key_wif> is also optional; its presence enables Sigma signing for 1-Sat Ordinals.

2. Commit the changes by clicking "Save".

The BSV operational functions will subsequently be accessible to Cursor's artificial intelligence under the "Bitcoin SV" service namespace.

Alternative via npm

If your preference leans towards using npm over 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>"
      }
    }
  }
}

Integration with Claude for Desktop

To connect this service instance to Claude for Desktop:

1. Launch Claude for Desktop and navigate to Claude > Settings > Developer.
2. Select "Edit Config".

Access the Claude configuration JSON file using your preferred text editor. Alternatively, use the command line:

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

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

1. Incorporate the BSV MCP server definition into your configuration: json { "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. Substitute <your_private_key_wif> with your active private key WIF.
3. Save the modification and initiate a restart of Claude for Desktop.
4. The BSV utility set will manifest when you activate the tools icon (represented by a hammer) within the Claude interface.

npm Alternative (Claude)

Should npm be preferred over Bun, substitute the "command" field value with "npx".

Operational Tool Catalog

The toolkit is systematically organized into functional domains:

Wallet Operations Module

These utilities manage fundamental BSV ledger access and custodial functions:

Function Name	Purpose	Illustrative Output
wallet_getPublicKey	Fetches the public key corresponding to a specified protocol identifier and key index.	{"publicKey":"032d0c73eb9270e9e009fd1f9dd77e19cf764fbad5f799560c4e8fd414e40d6fc2"}
wallet_createSignature	Generates a digital cryptographic signature over specified input data.	{"signature":[144,124,85,193,226,45,140,249,9,177,11,167,33,215,209,38,...]}
wallet_verifySignature	Validates a cryptographic signature against its accompanying data payload.	{"isValid":true}
wallet_encryption	Consolidated function for data scrambling (encryption) and unscrambling (decryption) utilizing derived wallet cryptographic credentials. Usage Examples: 1. Data obfuscation: "Encrypt this message: Hello World" 2. Data recovery: "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 the associated BSV address, optionally derived via a specific path structure.	{"address":"1ExampleBsvAddressXXXXXXXXXXXXXXXXX","status":"ok"}
wallet_sendToAddress	Dispatches BSV units to a target address, supporting input specified in either native BSV or equivalent USD value.	{"status":"success","txid":"a1b2c3d4e5f6...","satoshis":1000000}
wallet_purchaseListing	Executes the acquisition of digital collectibles (NFTs or BSV-20/BSV-21 tokens) listed on integrated marketplaces.	{"status":"success","txid":"a1b2c3d4e5f6...","type":"nft","origin":"abcdef123456..."}
wallet_createOrdinals	Facilitates the creation and inscription of digital assets (Ordinals) onto the BSV ledger.	{"txid":"a1b2c3d4e5f6...","inscriptionAddress":"1ExampleAddress...","contentType":"image/png"}

BSV Ledger Interaction Tools

Functions for interfacing directly with the BSV network and ledger state:

Function Name	Purpose	Illustrative Output
bsv_getPrice	Retrieves the real-time valuation of BSV from external exchange feeds.	Current BSV price: $38.75 USD
bsv_decodeTransaction	Deconstructs a provided BSV transaction payload to reveal its constituent parts.	{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,"inputs":[...],"outputs":[...]}
bsv_explore	Advanced ledger querying utility accessing WhatsOnChain API endpoints.	{"chain_info":{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"0000000000..."}}

Ordinals Ecosystem Tools

Specialized modules for managing unique digital artifacts (NFTs) on BSV:

Function Name	Purpose	Illustrative Output
ordinals_getInscription	Fetches comprehensive metadata for a designated ordinal asset identifier.	{"id":"a1b2c3d4e5f6...","origin":"a1b2c3d4e5f6...","contentType":"image/png","content":"iVBORw0KGgoAAA..."}
ordinals_searchInscriptions	Executes criterion-based searches across the registry of inscribed assets.	{"results":[{"id":"a1b2c3...","contentType":"image/png","owner":"1Example..."},...]}
ordinals_marketListings	Aggregates current market offerings for NFTs, BSV-20 fungible tokens, and BSV-21 tokens via a standardized retrieval schema.	{"results":[{"txid":"a1b2c3...","price":9990000,"tick":"PEPE","listing":true},...]}
ordinals_marketSales	Queries historical transaction records for BSV-20 and BSV-21 token secondary market exchanges.	{"results":[{"txid":"a1b2c3...","price":34710050,"tick":"$BTC","sale":true},...]}
ordinals_getTokenByIdOrTicker	Retrieves the canonical definition details for a specific BSV20 token designation.	{"tick":"PEPE","max":"21000000","lim":"1000","dec":"2"}

General Purpose Utilities

Functions providing common data transformation services:

Function Name	Purpose	Illustrative Output
utils_convertData	Transforms input string data across specified encoding modalities (UTF-8, hexadecimal, Base64, raw byte array). Required Inputs: - data (Input String): The content subject to transformation. - from (Source Encoding): Encoding scheme (utf8, hex, base64, or binary). - to (Target Encoding): Desired resulting encoding scheme (utf8, hex, base64, or binary). Operational Examples: - UTF-8 to hex: {"data": "hello world", "from": "utf8", "to": "hex"} yields 68656c6c6f20776f726c64 - UTF-8 to base64: {"data": "Hello World", "from": "utf8", "to": "base64"} yields SGVsbG8gV29ybGQ= - base64 to UTF-8: {"data": "SGVsbG8gV29ybGQ=", "from": "base64", "to": "utf8"} yields Hello World - hex to base64: {"data": "68656c6c6f20776f726c64", "from": "hex", "to": "base64"} yields aGVsbG8gd29ybGQ= Constraints: - All three input specifications are mandatory. - Output is returned as a transformed string representation. - For binary conversions, data representation involves an array of numerical byte values.	"SGVsbG8gV29ybGQ=" (Result of encoding "Hello World" from UTF-8 into Base64)

MNEE Token Management

Tools dedicated to the MNEE fungible token standard on BSV:

Function Name	Purpose	Illustrative Output
mnee_getBalance	Queries the current MNEE token holding associated with the connected wallet identity.	{"balance": {"amount": 2900, "decimalAmount": 0.029}}
mnee_sendMnee	Initiates the transfer of MNEE units to a specified ledger address, capable of handling MNEE quantity or equivalent USD valuation for the transfer.	{"success": true, "txid": "d1ce853934964e6c1fe9f44c918a824f175c6ab466b966f49ebc0682a8318895", "rawtx": "0100000002a0be40d8942015f1...", "mneeAmount": 0.01, "usdAmount": "$0.01", "recipient": "15mNxEkyKJXPD8amic6oLUjS45zBKQQoLu"}
mnee_parseTx	Deconstructs an MNEE transaction record to extract granular details regarding operations and value flows. All monetary figures are denominated in atomic units, assuming a fixed precision of 5 decimal places (i.e., 1000 atomic units equate to 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}]}

Interacting with Tools via MCP

After establishing connectivity, users can employ conversational language to invoke Bitcoin SV functionalities through their designated AI companion.

Wallet Interaction Examples

• "Retrieve the current Bitcoin SV account identifier."
• "Transfer 0.01 BSV to the address 1ExampleBsvAddressXXXXXXXXXXXXXXXXX."
• "Execute a transfer equivalent to $5 USD in BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX."
• "Remit 0.01 MNEE to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX."
• "Query the current balance of MNEE tokens."
• "Analyze the operational data contained within this MNEE transaction ID."
• "Encrypt the following text utilizing my wallet's cryptographic assets."
• "Unscramble this previously encoded payload."
• "Acquire the digital collectible identified by this transaction output: txid_vout."
• "Execute the purchase protocol for the specified BSV-20 token listing: txid_vout."

Ordinals (Digital Collectibles) Queries

• "Display the metadata for the ordinal asset identified by outpoint 6a89047af2cfac96da17d51ae8eb62c5f1d982be2bc4ba0d0cd2084b7ffed325_0."
• "Initiate a search for 'Pixel Zoide' digital collectibles."
• "Present the active market listings for BSV digital artifacts."
• "Show prevailing market listings associated with the BSV-20 ticker PEPE."
• "Retrieve records of recent secondary market transactions for BSV-20 tokens."

Ledger Operations

• "What is the present market exchange rate for BSV?"
• "Provide a detailed structural breakdown of this BSV transaction: (transaction hex or ID)."
• "Fetch the most recent status report for the Bitcoin SV network state."
• "Examine block details corresponding to height 800000."
• "Investigate the transaction sequence affiliated with address 1ExampleBsvAddressXXXX."
• "Determine the presently unspent transaction outputs (UTXOs) associated with my wallet's addresses."
• "Retrieve comprehensive information for the transaction hash a1b2c3d4e5f6..."

Data Encoding Transformations

• "Transform the string 'Hello World' from UTF-8 encoding into its hexadecimal representation."

MCP Contextual Knowledge Access

The BSV MCP service furnishes specialized instructional prompts and reference materials accessible directly through the MCP interface. These resources empower AI models to supply enhanced, technically precise contexts regarding Bitcoin SV architectures.

Available Instructional Prompts

The server makes the following educational knowledge modules available for direct retrieval:

Ordinals Knowledge Base

• Designator: bitcoin_sv_ordinals
• Synopsis: Thorough documentation covering Bitcoin SV ordinals, including their conceptual basis, operational mechanics, and utilization protocols.
• Activation: Prompt the assistant regarding "Bitcoin SV ordinals" or "1Sat Ordinals" to access this content.

BSV Software Development Kit (SDK) Knowledge Modules

A curated suite of prompts detailing the components of the Bitcoin SV SDK:

• General Synopsis
• Designator: bitcoin_sv_sdk_overview
• Synopsis: High-level summary of the BSV SDK's objectives and primary structural elements.

• Activation: "Provide an overview of the BSV SDK" or "Define the Bitcoin SV SDK."

• Wallet Procedures

• Designator: bitcoin_sv_sdk_wallet
• Synopsis: Specific documentation concerning custodial functions within the BSV SDK.

• Activation: "Detail wallet management protocols in the BSV SDK."

• Transaction Construction

• Designator: bitcoin_sv_sdk_transaction
• Synopsis: In-depth specifications related to constructing and manipulating transactions.

• Activation: "Elucidate BSV SDK transaction assembly" or "How are transactions built using the BSV SDK?"

• Identity Verification

• Designator: bitcoin_sv_sdk_auth
• Synopsis: Information regarding identity assertion and verification protocols integrated into the BSV SDK.

• Activation: "Describe authentication mechanisms within the BSV SDK."

• Cryptography Primitives

• Designator: bitcoin_sv_sdk_cryptography
• Synopsis: Documentation on digital signing, data encryption, and verification services.

• Activation: "Explain cryptographic capabilities of the BSV SDK."

• Scripting Language

• Designator: bitcoin_sv_sdk_script
• Synopsis: Guidance on working with Bitcoin Scripting logic and smart contract features.

• Activation: "How do I engage with Bitcoin scripts using the BSV SDK?"

• Fundamental Structures

• Designator: bitcoin_sv_sdk_primitives
• Synopsis: Overview of the foundational data types and structural models employed by the BSV SDK.
• Activation: "List the data primitives available in the BSV SDK."

Reference Documentation

The server also grants access to official Bitcoin Request for Comments (BRC) documentation and project metadata:

Version History Reference

• Designator: bsv-mcp-changelog
• Synopsis: Chronological record of version releases and modifications made to the BSV MCP service.
• Activation: "Display the BSV MCP revision history" or "What are the latest updates?"

BRC Specification Repository

• BRCs Index
• Designator: brcs_readme
• Synopsis: Foundational document summarizing the entire repository of Bitcoin SV protocol specifications (BRCs).

• Activation: "Present the overview for Bitcoin SV BRCs."

• BRCs Table of Contents

• Designator: brcs_summary
• Synopsis: A structured index mapping all documented Bitcoin SV BRCs.

• Activation: "Provide a consolidated summary of Bitcoin SV BRCs."

• Specific BRC Specifications

• Designator: brc_spec
• Synopsis: Mechanism to retrieve the full text of any BRC document based on its category and sequential number.
• Activation: "Detail the contents of BRC 8 concerning Transaction Envelopes" or "What is specified in BRC 1?"

BRC Thematic Groupings

The BRC documents are categorized under the following functional areas: - Wallet - Transactions - Scripts - Tokens - Overlays - Payments - Peer-to-Peer - Key Derivation - Outpoints - Opinions - State Machines - Apps

Leveraging Knowledge Resources

AI entities can employ these knowledge prompts to generate responses that are more granular and factually robust concerning Bitcoin SV technologies. As an end-user, your interactions can involve:

1. Targeted Inquiry: "Provide insight into Bitcoin SV ordinals" or "Explain the transaction assembly process via the BSV SDK."
2. Specification Request: "What are the criteria outlined in BRC 8?" or "Fetch the definition for BRC governing Transaction Creation."
3. Broad Context Retrieval: "Summarize the purpose of the BSV SDK" or "Display the complete BRC index."

These integrated resources significantly augment the AI's inherent knowledge graph, facilitating expert-level responses even for highly complex Bitcoin SV concepts.

Operational Flow of MCP

When an interaction is initiated with an MCP-compliant artificial intelligence system:

1. The AI parses the user's directive to ascertain the requisite operational tools.
2. Upon securing necessary user consent, it invokes the corresponding BSV MCP service function.
3. The server executes the requested operation against the Bitcoin SV ledger infrastructure.
4. The resultant data payload is relayed back to the controlling AI entity.
5. The AI synthesizes this result into a coherent, naturally phrased conclusion for the user.

Configuration Parameters

The BSV MCP server permits fine-grained functional adjustments via environment variables to enable or deactivate specific system components:

System Component Control

Environment Variable	Default State	Functional Effect
DISABLE_PROMPTS	false	Set to true to suppress all integrated instructional modules.
DISABLE_RESOURCES	false	Set to true to suppress all reference materials (BRCs, version log).
DISABLE_TOOLS	false	Set to true to deactivate all operational service functions.

Tool Subset Configuration

Environment Variable	Default State	Functional Effect
DISABLE_WALLET_TOOLS	false	Set to true to exclude Bitcoin custodial functions.
DISABLE_MNEE_TOOLS	false	Set to true to exclude MNEE token specific utilities.
DISABLE_BSV_TOOLS	false	Set to true to exclude core BSV network interaction tools.
DISABLE_ORDINALS_TOOLS	false	Set to true to exclude digital asset (NFT/Ordinal) management tools.
DISABLE_UTILS_TOOLS	false	Set to true to exclude general data conversion functions.
IDENTITY_KEY_WIF	unset	Optional WIF for a dedicated identity key; activation enforces sigma-protocol signing on ordinal inscriptions for trust verification and identity anchoring.
DISABLE_BROADCASTING	false	Set to true to operate in simulation mode, returning raw transaction hex instead of broadcasting; ideal for pre-execution validation.

Execution Examples

To run the server configured for knowledge delivery only (prompts and resources active, all tools disabled):

DISABLE_TOOLS=true bunx bsv-mcp@latest

To initiate the service supporting only non-custodial BSV network inquiries (disabling wallet, MNEE, ordinals, and utilities):

DISABLE_PROMPTS=true DISABLE_RESOURCES=true DISABLE_WALLET_TOOLS=true DISABLE_MNEE_TOOLS=true DISABLE_ORDINALS_TOOLS=true DISABLE_UTILS_TOOLS=true bunx bsv-mcp@latest

To utilize all functions except those requiring wallet access:

DISABLE_WALLET_TOOLS=true bunx bsv-mcp@latest

To perform transaction generation in a non-publishing (dry-run) context:

DISABLE_BROADCASTING=true bunx bsv-mcp@latest

Debugging and Support

If operational impediments arise when utilizing the BSV MCP service:

Connectivity Concerns

1. Verify that either Bun or Node.js is correctly installed on the host system.
2. Confirm the environment variable PRIVATE_KEY_WIF is configured accurately.
3. Ensure the connecting client possesses MCP compatibility and proper setup parameters.
4. Scrutinize the client's console logs for reported anomalies.

Updating Bun

Maintaining an up-to-date Bun installation is crucial for ongoing compatibility:

# Execute the update procedure for Bun
bun upgrade

To confirm the presently deployed Bun version:

bun --version

Diagnostic Logging Channels

For Claude for Desktop users, log inspection points are located at:

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

# Windows
type %APPDATA%\Claude\Logs\mcp*.log

For Cursor, access diagnostic output via Settings → Extensions → Model Context Protocol logs.

Development Roadmap Notes (Recent Changes)

• Broadcast Suppression Added: Introduction of DISABLE_BROADCASTING variable to halt on-chain transaction submission.
• Advanced Explorer Integration: Implementation of bsv_explore leveraging WhatsOnChain services (mainnet/testnet support).
• Function Consolidation: Merged redundant wallet_encrypt and wallet_decrypt into the unified wallet_encryption interface.
• Marketplace Unification: Enhanced support across listings, sales reporting, and purchases for NFTs and BSV-20/21 tokens.
• Optimization: Incorporated response caching and streamlined API pathway architecture.
• Input Validation: Improved robustness in verifying private key authenticity and function parameter adherence.

Bitcoin SV Blockchain Explorer Utility (bsv_explore)

The bsv_explore function grants broad programmatic access to the Bitcoin SV ledger via the WhatsOnChain data access layer. This robust exploration module permits querying of network statistics, block records, transaction metadata, and address balances.

Supported Data Retrieval Paths

The utility services the following data access categories and specific methods:

Network Status

Path	Functionality Summary	Dependencies	Sample Retrieval
chain_info	Network operational metrics, difficulty factors, chain progress.	None	{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"0000000000..."}
chain_tips	Status of the active chain heads, including height and validation state.	None	[{"height":826458,"hash":"000000000000...","branchlen":0,"status":"active"}]
circulating_supply	Current metric of verifiable BSV supply in circulation.	None	{"bsv":21000000}
peer_info	Statistics regarding established network peer connections.	None	[{"addr":"1.2.3.4:8333","services":"000000000000...","lastsend":1621234567}]

Block Records

Path	Functionality Summary	Dependencies	Sample Retrieval
block_by_hash	Retrieves complete block structure using its hash identifier.	blockHash	{"hash":"000000000000...","confirmations":1000,"size":1000000,...}
block_by_height	Retrieves complete block structure using its sequential height index.	blockHeight	{"hash":"000000000000...","confirmations":1000,"size":1000000,...}
tag_count_by_height	Statistical summary of registered protocol tags within a specific block height.	blockHeight	{"tags":{"amp":3,"bitkey":5,"metanet":12,"planaria":7,"b":120}}
block_headers	Fetches the most recent ten block headers.	None	[{"hash":"000000000000...","height":826458,"version":536870912,...},...]
block_pages	Retrieves sequential pages of transaction identifiers associated with large blocks.	blockHash, optional: pageNumber	["tx1hash","tx2hash","tx3hash",...]

Statistical Metrics

Path	Functionality Summary	Dependencies	Sample Retrieval
block_stats_by_height	Detailed metrics for a block at a given height.	blockHeight	{"size":123456,"txCount":512,"outputTotal":54.12345678,"outputTotalUsd":2345.67,...}
block_miner_stats	Aggregated statistics on block production across a time span.	optional: days (default 7)	{"blocks":{"miner1":412,"miner2":208,...},"total":1008}
miner_summary_stats	Consolidated summary of mining activity over a set period.	optional: days (default 7)	{"totalBlocks":1008,"totalFees":1.23456789,"totalFeesUsd":53.67,...}

Transaction Data Retrieval

Path	Functionality Summary	Dependencies	Sample Retrieval
tx_by_hash	Retrieves the full structured data for a transaction.	txHash	{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,...}
tx_raw	Fetches the raw, serialized hexadecimal representation of a transaction.	txHash	"01000000012345abcdef..."
tx_receipt	Retrieves metadata related to transaction confirmation status.	txHash	{"blockHash":"000000000000...","blockHeight":800000,"confirmations":26458}
bulk_tx_details	Requests structured data for multiple transactions concurrently.	txids (array)	[{"txid":"a1b2c3d4e5f6...","version":1,...}, {"txid":"b2c3d4e5f6a7...","version":1,...}]

Account/Address Querying

Path	Functionality Summary	Dependencies	Sample Retrieval
address_history	Lists all transactions touching an address.	address, optional: limit	[{"tx_hash":"a1b2c3d4e5f6...","height":800000},...]
address_utxos	Enumerates unspent outputs belonging to an address.	address	[{"tx_hash":"a1b2c3d4e5f6...","tx_pos":0,"value":100000},...]

Network Diagnostics

Path	Functionality Summary	Dependencies	Sample Retrieval
health	Connectivity and synchronization status check.	None	{"status":"synced"}

Operational Prompts

The bsv_explore utility responds effectively to natural language commands such as:

"Retrieve the current Bitcoin SV network statistics."
"Examine the constituent details of block height #800000."
"Fetch the protocol tag distribution metrics for block height #800000."
"Obtain the chronological transaction records for address 1ExampleBsvAddressXXXXXXXX."
"List all confirmed, unspent outputs associated with my wallet's address."
"Inspect the full structure for transaction ID a1b2c3d4e5f6..."
"Report the present volume of BSV tokens in circulation."
"Present the sequence of the ten most recently confirmed block headers."
"Retrieve the transaction identifiers for the second page of a large block record."
"Provide aggregated statistical data for block #800000."
"What are the block production statistics across the last 14 solar cycles?"
"Summarize the mining network activity spanning the preceding 30 days."
"Fetch detailed object data for multiple specified transactions simultaneously."

Internally, the tool maps these requests to specific parameter configurations:

• endpoint: The target WhatsOnChain path (e.g., chain_info, tx_by_hash).
• network: Specifies the ledger subset to query (main or test).
• Endpoint-specific arguments:
• blockHash: Required for block_by_hash and block_pages queries.
• blockHeight: Required for block indexing calls like block_by_height.
• pageNumber: Used for pagination when querying block_pages.
• days: Duration parameter for time-series mining reports (defaults to 7).
• txHash: Identifier for transaction-centric functions.
• txids: An array input for batch transaction data retrieval.
• address: The public key hash for address-based lookups.
• limit: Optional constraint on the cardinality of results returned for address_history.

Network Selection

Operations can target either the live ledger or the testing environment:

• main: The primary, production Bitcoin SV ledger (default setting).
• test: The Bitcoin SV test network.

Development Guide

Project Initialization

For individuals intending to contribute code or execute the project locally:

1. Obtain a local copy of the repository: bash git clone https://github.com/b-open-io/bsv-mcp.git cd bsv-mcp

2. Install required software dependencies: bash bun install # Alternatively, using npm: npm install

Server Launch Procedure

To commence service operation:

bun run index.ts
# Alternatively, using npm:
npm run start

Running Unit and Integration Tests

bun test
# Alternatively, using npm:
npm test

Licensing Information

This software is distributed under the terms of the MIT License; refer to the LICENSE file for comprehensive licensing details.