---
slug: "bitcoin"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/moncho/bitcoin-mcp@main/README.md"
repo: "https://github.com/moncho/bitcoin-mcp"
source_file: "README.md"
branch: "main"
---
# 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:
```bash
git clone https://github.com/moncho/bitcoin-mcp.git
cd bitcoin-mcp
```

2. Install dependencies:
```bash
go mod download
```

3. Build the server:
```bash
go build -o bitcoin-mcp
```

## Configuration

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

```json
{
    "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:
```bash
bitcoind -server -rpcuser=your_rpc_username -rpcpassword=your_rpc_password
```

2. Start the MCP server:
```bash
./bitcoin-mcp -config config.json
```

Or using environment variables:
```bash
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
```bash
curl -X POST http://localhost:8080/api/v1/blockchain/info
```

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

### Get Mempool Information
```bash
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:
```bash
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](https://github.com/moncho/bitcoin-mcp/blob/HEAD/CONTRIBUTING.md) when submitting changes.

## Documentation

For detailed API documentation and specifications, see:
- [API Specification](https://github.com/moncho/bitcoin-mcp/blob/HEAD/SPEC.md)
- [GoDoc Documentation](https://godoc.org/github.com/moncho/bitcoin-mcp)

## License

[Specify License Information]

## Support

For support, please:
1. Check the [documentation](https://github.com/moncho/bitcoin-mcp/blob/HEAD/SPEC.md)
2. Search existing issues
3. Create a new issue if needed

## Acknowledgments

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