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.
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:
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 · 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 · 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 · 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
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
{
"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 · 2026-03-15 · closed · 0 comments
The remaining reports are on the project's issue tracker.