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

1. Clone the repository:

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

1. Install dependencies:

go mod download

1. 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

1. Start your Bitcoin Core node with RPC enabled:

bitcoind -server -rpcuser=your_rpc_username -rpcpassword=your_rpc_password

1. 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

1. Add the method to the Bitcoin client in pkg/bitcoin/client.go
2. Create or update the corresponding tool in pkg/tools/
3. Register the tool in the appropriate category
4. 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

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Please follow the Contributing Guidelines when submitting changes.

Documentation

For detailed API documentation and specifications, see:

• API Specification
• GoDoc Documentation

License

[Specify License Information]

Support

For support, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue if needed

Acknowledgments

• Bitcoin Core developers
• Go community
• All contributors to this project