Bitcoin MCP Server

A Go-based service that provides a unified interface to interact with a Bitcoin node through various RPC commands using the Model Context Protocol (MCP). The server organizes Bitcoin RPC functionality into logical categories and provides a clean, well-documented API for accessing blockchain data and operations.

Features

Comprehensive Bitcoin RPC interface using Model Context Protocol
Organized by functional categories:
- Blockchain operations
- Mempool operations
- UTXO operations
- Blockchain management
Secure authentication
Comprehensive error handling
Clean and documented API

Prerequisites

Go 1.24 or later
Bitcoin Core node with RPC enabled
Basic understanding of Bitcoin RPC commands

Installation

Clone the repository:

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

Install dependencies:

go mod download

Build the server:

go build -o bitcoin-mcp

Configuration

Create a configuration file (config.json) with the following structure:

{
    "bitcoin": {
        "rpc_url": "http://localhost:8332",
        "username": "your_rpc_username",
        "password": "your_rpc_password"
    },
    "server": {
        "port": 8080,
        "host": "localhost"
    }
}

Running the Server

Start your Bitcoin Core node with RPC enabled:

bitcoind -server -rpcuser=your_rpc_username -rpcpassword=your_rpc_password

Start the MCP server:

./bitcoin-mcp -config config.json

Or using environment variables:

BITCOIN_RPC_URL=http://localhost:8332 \
BITCOIN_RPC_USER=your_rpc_username \
BITCOIN_RPC_PASS=your_rpc_password \
./bitcoin-mcp

API Usage

The server provides a RESTful API for accessing Bitcoin RPC commands. Here are some examples:

Get Blockchain Information

curl -X POST http://localhost:8080/api/v1/blockchain/info

Get Block Data

curl -X POST http://localhost:8080/api/v1/blockchain/block \
  -H "Content-Type: application/json" \
  -d '{"blockhash": "0000000000000000000123456789abcdef", "verbose": true}'

Get Mempool Information

curl -X POST http://localhost:8080/api/v1/mempool/info

Development

Project Structure

bitcoin-mcp/
├── cmd/
│   └── server/          # Main server application
├── pkg/
│   ├── bitcoin/         # Bitcoin RPC client
│   └── tools/           # RPC command implementations
├── config.json          # Configuration file
└── README.md           # This file

Adding New RPC Commands

Add the method to the Bitcoin client in pkg/bitcoin/client.go
Create or update the corresponding tool in pkg/tools/
Register the tool in the appropriate category
Add tests for the new functionality

Testing

Run the test suite:

go test ./...

Security Considerations

Never expose RPC credentials in public repositories
Use secure passwords for RPC access
Consider rate limiting for public APIs
Validate all input parameters
Sanitize error messages

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

Please follow the Contributing Guidelines when submitting changes.

Documentation

For detailed API documentation and specifications, see:

License

[Specify License Information]

Support

For support, please:

Check the documentation
Search existing issues
Create a new issue if needed

Acknowledgments

Bitcoin Core developers
Go community
All contributors to this project