# Reported issues for Bitcoin MCP

Pod holds 12 of 12 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Bitcoin MCP](/mcp/bitcoin-mcp).

## Most discussed

### Add `--log-level` CLI flag for debug logging

## What

Add a `--log-level` CLI flag to control logging verbosity. Currently the log level is hardcoded to `INFO` on line 23 of `server.py`:

```python
logging.basicConfig(level=logging.INFO, stream=sys.stderr)
```

## Why

When troubleshooting connection issues or debugging tool behavior, users need `DEBUG` level logging to see:
- Which RPC backend was selected (local node vs Satoshi API)
- Individual RPC call details
- Response timing

Currently there is no way to enable debug output without 

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/12) · 2026-03-21 · closed · 3 comments

### HRF Roadmap: Lightning tools for bitcoin-mcp

## Why this matters

Lightning is a core usability layer for censorship-resistant Bitcoin payments. Adding Lightning support to bitcoin-mcp gives local AI assistants practical Bitcoin payment awareness without forcing users through centralized platforms.

## Scope

Add Lightning Network tools to bitcoin-mcp for invoice and payment workflows.

## Acceptance criteria

- [ ] Add invoice creation tool or document supported backend requirements
- [ ] Add payment verification tool
- [ ] Add channel or

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/32) · 2026-04-21 · open · 1 comment

### Add example configuration for Zed editor

## What

Add a Zed editor MCP configuration example to the `examples/` folder and mention it in the README Quick Start section.

The `examples/` folder already has configs for Claude Desktop, Cursor, and Windsurf — but Zed is missing despite having MCP support since v0.167.

## Why

Zed is a fast-growing editor with native MCP support. Adding a config example removes friction for Zed users discovering bitcoin-mcp. The existing examples for other editors show this is an established pattern in the

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/13) · 2026-03-21 · closed · 1 comment

### Tool: decode_xpub — derive addresses and metadata from extended public key

## Feature Request

**Tool name:** `decode_xpub`

### What it should do
Accept an extended public key (xpub/ypub/zpub) and return metadata + derived addresses. Useful for agents doing wallet analysis or watch-only wallet setups.

### Expected inputs
```python
xpub: str              # Extended public key (xpub/ypub/zpub/tpub)
derive_count: int = 5  # Number of addresses to derive (max 20)
account: int = 0       # BIP44 account index
```

### Expected output
```json
{
  "network": "mainnet",
  "ty

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/2) · 2026-03-15 · closed · 1 comment

### Add `py.typed` marker and improve type hints in `l402_client.py`

## What

Two improvements for type checking support:

1. **Add `py.typed` marker file** — `src/bitcoin_mcp/py.typed` (empty file). This tells type checkers (mypy, pyright) that the package supports inline type hints. Without it, tools like VS Code show bitcoin-mcp as "partially unknown."

2. **Add return type annotations to `l402_client.py`** — Several methods are missing return types:
   - `L402Client.close()` → `None`
   - `L402Client.__enter__()` → `"L402Client"`  (or `Self` with `typing_exte

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/11) · 2026-03-21 · closed · 0 comments

### Add input validation for address parameters

## What

Several tools accept Bitcoin addresses as string parameters but do no client-side validation before sending them to the RPC. If a user passes a completely invalid string (e.g., an empty string, a URL, or random text), the error comes back as a raw RPC error message that is unhelpful.

Affected tools:
- `get_address_utxos(address)`
- `validate_address(address)`
- `get_address_balance(address)`
- `get_address_history(address)`

## Why

Better input validation means:
1. Faster, clearer err

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/10) · 2026-03-21 · closed · 0 comments

### Add `--transport` flag to support SSE in addition to stdio

## What

The CLI currently only supports stdio transport (the default for MCP). Add a `--transport` flag that lets users choose between `stdio` (default) and `sse` (Server-Sent Events over HTTP).

## Why

SSE transport is useful for:
- Web-based MCP clients that cannot use stdio
- Running bitcoin-mcp as a persistent HTTP service behind a reverse proxy
- Development/debugging (you can curl the SSE endpoint directly)

The `mcp` library already supports SSE — this is just wiring up the CLI flag.

#

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/9) · 2026-03-21 · closed · 0 comments

### Add tests for PSBT security analysis tool

## What

The `analyze_psbt_security` tool in `server.py` has no test coverage. This tool analyzes Partially Signed Bitcoin Transactions for security risks — it is one of the most safety-critical tools in the entire server.

## Why

PSBT analysis directly affects user funds. If it fails to flag a dangerous transaction or crashes on malformed input, users could lose Bitcoin. This is the highest-priority untested tool.

## What to test

1. **Valid PSBT** — mock `decodepsbt` RPC to return a normal P

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/8) · 2026-03-21 · closed · 0 comments

## Most recent

### Add tests for MCP resources (7 resources have zero coverage)

## What

All 7 MCP resources defined in `server.py` have no test coverage:

- `resource_connection_status` — `bitcoin://connection/status`
- `resource_node_status` — `bitcoin://node/status`
- `resource_current_fees` — `bitcoin://fees/current`
- `resource_mempool_snapshot` — `bitcoin://mempool/snapshot`
- `resource_script_opcodes` — `bitcoin://protocol/script-opcodes`
- `resource_address_types` — `bitcoin://protocol/address-types`
- `resource_sighash_types` — `bitcoin://protocol/sighash-types`

#

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/7) · 2026-03-21 · closed · 0 comments

### Add unit tests for L402 client

## What

`src/bitcoin_mcp/l402_client.py` has zero test coverage. It implements the L402 Lightning payment protocol (macaroon + invoice challenge-response flow) but none of the logic is tested.

## Why

The L402 client handles real money flows — token caching, price limit enforcement, challenge parsing, and retry logic. Untested payment code is a liability. Adding tests here improves confidence for anyone extending Lightning support.

## What to test

At minimum, cover these cases:

1. **`_parse

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/6) · 2026-03-21 · closed · 0 comments

### Resource: bitcoin://fees/history — fee rate history over last 7 days

## Feature Request

**Resource URI:** `bitcoin://fees/history`

### What it should do
Return a time-series of fee rates over the past 7 days (hourly buckets). Currently agents can only get the *current* fee snapshot via `bitcoin://fees/current`. Historical context helps agents advise on whether fees are high/low relative to recent norms.

### Expected output
```json
{
  "period": "7d",
  "buckets": [
    {"timestamp": 1710000000, "fast_sat_vb": 45, "medium_sat_vb": 22, "slow_sat_vb": 8},
    ...

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/3) · 2026-03-15 · closed · 0 comments

### Tool: get_address_transactions — paginated tx history for an address

## Feature Request

**Tool name:** `get_address_transactions`

### What it should do
Return paginated transaction history for a Bitcoin address. Agents frequently need to answer "what has this address sent/received?" and currently have to use `get_address_history` which returns summary data only.

### Expected inputs
```python
address: str           # Bitcoin address (bech32, P2PKH, P2SH)
limit: int = 10        # Max transactions to return  
offset: int = 0        # Pagination offset
```

### Ex

[Read the thread](https://github.com/Bortlesboat/bitcoin-mcp/issues/1) · 2026-03-15 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/Bortlesboat/bitcoin-mcp/issues).