Skip to main content
Glama
kukapay

bitcoin-utxo-mcp

by kukapay
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Remote

Bitcoin UTXO MCP

An MCP server that tracks Bitcoin's Unspent Transaction Outputs (UTXO) and block statistics, giving AI agents direct access to essential on-chain data.

GitHub License Python Version Status

Features

  • Tools:

    • get_utxo: Retrieves UTXO details for a given Bitcoin address, including the number of UTXOs, total value in BTC, and transaction details.

    • get_block_stats: Fetches transaction statistics for a specific Bitcoin block, including block hash, transaction count, total value, and block time.

  • Prompt:

    • analyze_bitcoin_flow: A reusable prompt template for LLMs to analyze Bitcoin funds flow, network health, and potential market impacts based on UTXO and block data.

Related MCP server: crypto-stocks-mcp

Installation

Prerequisites

Setup

  1. Clone the Repository:

    git clone https://github.com/kukapay/bitcoin-utxo-mcp.git
cd bitcoin-utxo-mcp

  2. Install dependencies:

    uv sync

  3. Install to Claude Desktop:

    Install the server as a Claude Desktop application:

    uv run mcp install main.py --name "Bitcoin UTXO"

    Configuration file as a reference:

    {
   "mcpServers": {
       "Bitcoin UTXO": {
           "command": "uv",
           "args": [ "--directory", "/path/to/bitcoin-utxo-mcp", "run", "main.py" ]
       }
   }
}

    Replace /path/to/bitcoin-utxo-mcp with your actual installation path.

Usage

Available Tools and Prompts

  • Tools:

    • get_utxo(address: str): Returns UTXO details for a Bitcoin address, e.g., "Address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa: 50 UTXOs, Total Value: 50.00000000 BTC, UTXO Details: ...".

    • get_block_stats(block_height: int): Returns block statistics, e.g., "Block Height: 0, Block Hash: 000000000019d668..., Transactions: 1, Total Value: 50.00000000 BTC, Block Time: 1231006505".

  • Prompt:

    • analyze_bitcoin_flow(): Generates a prompt for LLMs to analyze UTXO and block data, e.g., "Analyze the provided Bitcoin UTXO and block data: What do the UTXO distributions indicate about funds flow? ...".

Example Interaction

Below are examples of natural language prompts you might use in an MCP-compatible client (e.g., Claude Desktop) and the corresponding outputs from the server, based on hypothetical Blockchain.com API responses.

  1. Get UTXO for a Bitcoin Address:

    • Prompt: "Show me the UTXO details for the Bitcoin genesis address."

    • Command: get_utxo("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa")

    • Output:

      Address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa:
50 UTXOs
Total Value: 50.00000000 BTC
UTXO Details:
- TXID: 4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b, Value: 50.00000000 BTC, Confirmations: 800000

  2. Get Block Statistics:

    • Prompt: "What's the transaction data for the Bitcoin genesis block?"

    • Command: get_block_stats(0)

    • Output:

      Block Height: 0
Block Hash: 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f
Transactions: 1
Total Value: 50.00000000 BTC
Block Time: 1231006505

  3. Analyze Bitcoin Flow:

    • Prompt: "Analyze Bitcoin funds flow and network health."

    • Command: analyze_bitcoin_flow()

    • Output (prompt sent to LLM for analysis):

      Analyze the provided Bitcoin UTXO and block data:
- What do the UTXO distributions indicate about funds flow?
- How does the block statistics reflect network health (e.g., transaction volume, congestion)?
- Provide insights on potential market impacts or trends.

      • LLM Response (example, depends on the LLM):

        The UTXO distribution for the queried address shows a significant number of unspent outputs, indicating long-term holding behavior, possibly by an early adopter. The genesis block's single transaction with 50 BTC reflects the initial reward structure. Current block statistics suggest stable network health with consistent transaction volumes. High UTXO consolidation may signal preparation for large transfers, potentially impacting market liquidity if moved. Historically, such patterns precede price volatility.

License

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

Available Tools

2 tools
get_block_statsA

Get transaction statistics for a specific Bitcoin block.

Args:
    block_height (int): The height of the block

Returns:
    A string containing:
    - Block height
    - Block hash
    - Number of transactions
    - Total transaction value in BTC
    - Block time
ParametersJSON Schema
NameRequiredDescriptionDefault
block_heightYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While it describes what information is returned, it doesn't mention error conditions (e.g., invalid block height), performance characteristics, rate limits, authentication requirements, or whether this is a read-only operation. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear purpose statement followed by organized Args and Returns sections. Every sentence serves a purpose, though the Returns section could be slightly more concise by listing items without the 'A string containing' preamble.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (single parameter, specific purpose) and the presence of an output schema (implied by 'Has output schema: true'), the description provides adequate context. It explains the parameter meaning and outlines return content, though additional behavioral context would improve completeness for a tool with no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides clear semantic meaning for the single parameter ('The height of the block'), which compensates for the 0% schema description coverage. While it doesn't elaborate on constraints (e.g., valid range, format), it successfully explains what the parameter represents beyond the schema's basic type declaration.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get transaction statistics') and resource ('for a specific Bitcoin block'), distinguishing it from the sibling tool get_utxo which likely deals with unspent transaction outputs rather than block-level statistics. The verb+resource combination is precise and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when block-level transaction statistics are needed, but provides no explicit guidance on when to use this tool versus alternatives or any prerequisites. There's no mention of the sibling tool get_utxo or when one would be preferred over the other, leaving usage context incomplete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_utxoA

Get UTXO for a Bitcoin address.

Args:
    address (str): Bitcoin address (base58 or bech32 format)

Returns:
    A string containing:
    - Address
    - Number of UTXOs
    - Total value in BTC
    - List of UTXO details (txid, value, confirmations)
ParametersJSON Schema
NameRequiredDescriptionDefault
addressYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It describes the return format comprehensively but doesn't mention behavioral aspects like rate limits, authentication requirements, error conditions, or whether this is a read-only operation (though 'Get' implies it).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear purpose statement followed by well-organized Args and Returns sections. Every sentence earns its place by providing essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, the description doesn't need to explain return values, yet it provides a comprehensive overview of what the tool returns. Combined with the detailed parameter information, this creates a complete picture for a single-parameter query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by providing detailed parameter semantics: it specifies the parameter name ('address'), type ('str'), and acceptable formats ('base58 or bech32 format'), which goes well beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get UTXO') and resource ('for a Bitcoin address'), distinguishing it from the sibling tool 'get_block_stats' which presumably deals with block-level statistics rather than address-specific UTXO data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying it's for Bitcoin addresses, but doesn't explicitly state when to use this tool versus alternatives like 'get_block_stats' or other potential UTXO-related tools. However, the clear resource focus provides reasonable guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updates
    • First observedget_block_stats
    • First observedget_utxo
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes with no overlap. get_block_stats focuses on block-level transaction statistics, while get_utxo retrieves unspent transaction outputs for specific addresses. An agent can easily differentiate between these two operations.

Naming Consistency5/5

Both tools follow a consistent verb_noun naming pattern with get_ prefix and snake_case formatting. The naming convention is predictable and readable throughout the tool set.

Tool Count2/5

With only 2 tools, this server feels significantly under-scoped for Bitcoin UTXO operations. A Bitcoin UTXO-focused server would typically need more tools for comprehensive coverage, such as transaction broadcasting, fee estimation, or address validation.

Completeness2/5

The tool surface is severely incomplete for Bitcoin UTXO operations. While it provides read operations for blocks and addresses, it lacks essential capabilities like transaction creation, signing, broadcasting, fee estimation, or multi-address UTXO aggregation. This creates significant gaps that will cause agent failures in typical Bitcoin workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • crypto-stocks-mcp

    kukapay
    A
    license
    A
    quality
    F
    maintenance
    An MCP server that tracks real-time data for major crypto-related stocks to help AI agents analyze blockchain investment opportunities.
    3
    3
    MIT

  • MCP Mempool

    jaducku
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides AI agents with real-time and historical Bitcoin network data by wrapping the mempool.space WebSocket and REST APIs. It enables tracking addresses, monitoring blocks, and retrieving transaction details or fee estimates through natural language.
    MIT

  • treasury-mcp

    bjunjo
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that enables AI agents to query real-time Bitcoin network intelligence and corporate treasury data, including company holdings and SEC filings. It combines 49 core Bitcoin tools with specialized functions for tracking publicly traded companies and their Bitcoin assets.
    53
    MIT

Appeared in Searches