# mcp-mempool

MCP (Model Context Protocol) server for the [mempool.space](https://mempool.space) Bitcoin API. No API key required.

Lets any MCP client (Claude Code, Claude Desktop, etc.) query live Bitcoin data: recommended fees, mempool state, blocks, transactions, addresses, price.

## Tools

| Tool | Arguments | Returns |
|---|---|---|
| `get_recommended_fees` | — | Fee estimates in sat/vB (fastest, 30 min, 1 h, economy, minimum) |
| `get_mempool_stats` | — | Unconfirmed tx count, total vsize, total pending fees |
| `get_tip` | — | Current block height and hash |
| `get_recent_blocks` | `limit` (1-10, default 5) | Recent blocks: height, time, tx count, median fee, mining pool |
| `get_transaction` | `txid` (64 hex chars) | Confirmation status, fee, fee rate, inputs/outputs |
| `get_address` | `address` | Confirmed balance, received total, tx counts, pending delta |
| `get_price` | — | BTC price in USD, EUR, GBP, CAD, CHF, AUD, JPY |

## Install and build

```bash
npm install
npm run build
```

## Try it

`examples/client.mjs` spawns the server over stdio and calls each tool:

```bash
npm run example
```

## Use with Claude Code

```bash
claude mcp add mempool -- node /path/to/mcp-mempool/dist/index.js
```

Then ask, for example: *"quels frais je mets pour une transaction confirmée dans l'heure ?"*

## Use with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mempool": {
      "command": "node",
      "args": ["/path/to/mcp-mempool/dist/index.js"]
    }
  }
}
```

## Other networks / self-hosted instance

Set `MEMPOOL_API_BASE` to point elsewhere (default: `https://mempool.space/api`):

```json
{
  "mcpServers": {
    "mempool-testnet": {
      "command": "node",
      "args": ["/path/to/mcp-mempool/dist/index.js"],
      "env": { "MEMPOOL_API_BASE": "https://mempool.space/testnet4/api" }
    }
  }
}
```

Works with any mempool.space-compatible instance (e.g. a self-hosted one on your own node).

## Notes

- Uses the public REST API; heavy usage should point `MEMPOOL_API_BASE` at a self-hosted instance (mempool.space rate-limits aggressively).
- API errors are returned as MCP tool errors (`isError: true`) with the upstream message, so the model can react to them.

## License

MIT