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

2. Install dependencies:

go mod download

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

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