Tutorials
MCP: Interact with Bitcoin via an LLM

15min
The Model Context Protocol (MCP) is an open standard that enables developers to build secure, two-way connections between their data sources and AI-powered tools.
For additional information about MCP, its origins, and Claude, read more from the creators, Anthropic.
﻿
The Maestro MCP server allows for interacting with Bitcoin through the interface of an LLM client.
This server functionality provides the LLM with a set of tools for exploring blocks, transactions, addresses, and other aspects of the Bitcoin blockchain, allowing the LLM to not only retrieve and make infereances on on-chain data, but also to take action on behalf of the user; ie, serve as an agent.
In this tutorial, we will use Claude AI's Desktop client alongside the Maestro MCP server to communicate with the Bitcoin network via Maestro.
Some of the MCP server functionality will not work if you are using the Artist tier; a Composer-level subscription or higher will be needed to access the more advanced MCP features, such as those related to Mempool API activities.
Consult the pricing page for more information.
﻿
Installation
Requirements
Python >=3.10
Python MCP SDK >= 1.2.0
uv
Install UV
Bash
curl -LsSf https://astral.sh/uv/install.sh | sh
curl -LsSf https://astral.sh/uv/install.sh | sh
﻿
Setup Virual Environment
Bash
# Create a virtual environment
uv venv

# Activate virtual environment
# Linux/MacOS
source .venv/bin/activate
# Windows
# .venv\Scripts\activate

# Install dependencies
uv pip install .
# Create a virtual environment
uv venv

# Activate virtual environment
# Linux/MacOS
source .venv/bin/activate
# Windows
# .venv\Scripts\activate

# Install dependencies
uv pip install .
﻿
Configure Claude (Desktop)
Download Claude Desktop here.
Steps
Open Claude Desktop settings
﻿
Select Edit Config
﻿
Open the Claude App configuration file located at: ~/Library/Application Support/Claude/claude_desktop_config.json and copy the below contents into this file
You will need the following to continue:
Absolute path to uv; ie, which uv
Absolute path to maestro-mcp repo
A Maestro API key
JSON
{
  "mcpServers": {
    "maestro-mcp": {
      "command": "/ABSOLUTE/PATH/TO/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/maestro-mcp",
        "run",
        "maestro.py"
      ],
      "env": {
        "MAESTRO_BASE_URL": "https://xbt-mainnet.gomaestro-api.org/v0",
        "MAESTRO_API_KEY": "<MAESTRO_API_KEY>"
      }
    }
  }
}
{
  "mcpServers": {
    "maestro-mcp": {
      "command": "/ABSOLUTE/PATH/TO/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/maestro-mcp",
        "run",
        "maestro.py"
      ],
      "env": {
        "MAESTRO_BASE_URL": "https://xbt-mainnet.gomaestro-api.org/v0",
        "MAESTRO_API_KEY": "<MAESTRO_API_KEY>"
      }
    }
  }
}
﻿
Usage
Restart Claude after any change to either the claude_desktop_config.json or the source code.
Launch Claude Desktop
Locate hammer icon

﻿
View available MCP tools

﻿
Prompt Claude
Examples:
"Fetch the latest Bitcoin block"
"Get the blockchain info for Bitcoin"
"Fetch all UTXOs for this address: bc1prqpwzqqcfzlrtjz3at5kuz4zevqsmvxc5xjuzvg58y48leu67x0q0kvy85"
See usage for viewing all the available MCP tools.
﻿
You will need to approve the request within Claude.
Debugging
CLI inspector tool
﻿mcp-cli﻿
Logs
Bash
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-maestro-mcp.log
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-maestro-mcp.log
﻿
Support
If you are experiencing any trouble with the above, open an issue or reach out on Discord.
Overview
API Usage