<div align="center">

# Bitcoin Stamps MCP

**A Model Context Protocol server for [Bitcoin Stamps](https://stampchain.io) — 24 read-only tools over the stampchain.io explorer API, for any AI agent.**

[![PyPI](https://img.shields.io/pypi/v/stampchain-mcp?color=f7931a&label=PyPI)](https://pypi.org/project/stampchain-mcp/)
[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB)](https://pypi.org/project/stampchain-mcp/)
[![MCP](https://img.shields.io/badge/MCP-stdio%20%2B%20streamable%20HTTP-blue)](https://modelcontextprotocol.io)
[![Keys](https://img.shields.io/badge/keys-never-brightgreen)](#it-cannot-touch-a-wallet)
[![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)

</div>

> **Status (2026-09-15):** this Python server was the prototype. The work is going into the
> official [stampchain-io/stampchain-mcp](https://github.com/stampchain-io/stampchain-mcp) instead —
> first PR: [#6, align tools with the live v2 API](https://github.com/stampchain-io/stampchain-mcp/pull/6);
> the extra coverage (dispensers, holders, wallets, SRC-20 market, SRC-101, blocks) follows as a second PR.
> This repo stays as a reference and is **not published to PyPI**.

Bitcoin Stamps store data permanently in Bitcoin's UTXO set. [stampchain.io](https://stampchain.io) is the protocol's explorer and API. This server puts that API in front of Claude, Cursor, Windsurf, ElizaOS, LangGraph and every other MCP client — stamps, SRC-20 tokens and their market data, SRC-101 names, collections, dispensers and wallet balances — with no account, no key, and no way to move funds.

## Quick start

```bash
pip install stampchain-mcp
```

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{ "mcpServers": { "stampchain": { "command": "stampchain-mcp" } } }
```

**Cursor / Windsurf / Claude Code** — add a stdio MCP server with command `stampchain-mcp`. With `uv`: `uvx stampchain-mcp`.

Then ask: *"What's the floor on stamp 1?"*, *"Show me KEVIN's mint progress and market data"*, *"Which SRC-20 tokens have the highest market cap?"*, *"What does bc1q… hold?"*

## The 24 tools

| Area | Tool | What it answers |
|---|---|---|
| System | `stampchain_health` | Indexer sync state, block height, totals, circuit-breaker |
| System | `get_block` | A block by height or hash, or the last N blocks |
| Stamps | `search_stamps` | Free-text search: creator, CPID, stamp number, tx hash |
| Stamps | `list_stamps` | Paginated stamps with market filters (floor, holders, volume, quality) |
| Stamps | `get_stamp` | One stamp: creator, supply, mimetype, artwork URL, market data, lowest dispenser |
| Stamps | `stamp_holders` | Holders with amount and share of supply |
| Stamps | `stamp_dispensers` | Counterparty dispensers — the on-chain listings — with BTC rate and remaining |
| Stamps | `dispensers_by_address` | Everything a seller has listed, open or closed |
| Stamps | `stamp_activity` | Sends (owner to owner) or dispenses (purchases) for a stamp |
| Stamps | `stamps_in_block` | What was stamped in a block, latest by default |
| Wallets | `wallet_stamps` | Stamps an address holds, with value when known |
| Wallets | `wallet_balance` | BTC + stamps + SRC-20 for an address in one call |
| SRC-20 | `search_src20` | Tick search with mint progress and holders |
| SRC-20 | `list_src20_deploys` | Newest token deployments |
| SRC-20 | `get_src20` | Deploy + mint status + market data for one tick |
| SRC-20 | `src20_market` | Ranked market table, or one tick's prices, cap, volume, change |
| SRC-20 | `src20_balance` | Token balances of an address, all ticks or one |
| SRC-20 | `src20_holders` | Holder snapshot at the current block, largest first |
| SRC-20 | `src20_transactions` | DEPLOY / MINT / TRANSFER history by tick, op or block |
| SRC-20 | `src20_tx` | Decode one SRC-20 transaction |
| SRC-101 | `src101_deploys` | Bitcoin Name Service roots and their pricing |
| SRC-101 | `src101_wallet` | Names an address holds |
| Collections | `list_collections` | Collections with stamp numbers and edition counts |
| Collections | `get_collection` | One collection by id or name, with market metrics |

Every tool is a `GET` against `https://stampchain.io/api/v2`. Responses are the API's own JSON, passed through unchanged except that the base64 image payload on stamp records is dropped unless you ask for it.

## It cannot touch a wallet

The stampchain.io API also builds PSBTs, mints stamps and composes sends. **This server wraps none of that.** There is no tool that signs, builds or broadcasts a transaction, and no code path that could. Buying from a dispenser, minting, or transferring is a step the user takes in their own wallet — an agent using this server can find the listing and quote the price, and then hand off.

## Reading the market fields honestly

- Prices are in BTC (`price_btc`, `floor_price_btc`) and USD at the indexer's BTC price.
- `floor_price_btc` comes from open Counterparty dispensers; `null` means no open dispenser, not zero value.
- 24-hour volume is reliable. **7-day, 30-day and all-time volume are frequently `0` or `null`** because the upstream exchanges only publish 24h figures ([stampchain.io#1100](https://github.com/stampchain-io/stampchain.io/issues/1100)). Do not read a zero there as "no trading".
- `data_quality_score` (0–10) and `primary_exchange` / `exchange_sources` tell you how much to trust a row.

The tool descriptions repeat these caveats so a model sees them at call time.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `STAMPCHAIN_API_URL` | `https://stampchain.io` | Point at `https://dev.stampchain.io` or a self-hosted explorer |
| `STAMPCHAIN_API_KEY` | unset | Optional free API key sent as `X-API-Key`. Anonymous callers get ~100 requests/min; a key raises that 3–5x with a 50,000/day quota. Register with `POST https://stampchain.io/api/v2/keys` |
| `STAMPCHAIN_MCP_TRANSPORT` | `stdio` | Set `http` to serve streamable HTTP at `/mcp` with a landing page at `/` |
| `STAMPCHAIN_MCP_HOST` / `STAMPCHAIN_MCP_PORT` | `127.0.0.1` / `8791` | Bind address for HTTP mode |

## Hosting it

```bash
pip install "stampchain-mcp[http]"
STAMPCHAIN_MCP_TRANSPORT=http STAMPCHAIN_MCP_PORT=8791 stampchain-mcp
# MCP clients connect to http://host:8791/mcp ; browsers get a landing page at /
```

## Development

```bash
git clone https://github.com/sailorpepe/stampchain-mcp && cd stampchain-mcp
python -m venv .venv && .venv/bin/pip install -e ".[dev,http]"
.venv/bin/pytest -q            # live smoke tests against stampchain.io (skipped offline)
```

## Contributing

Issues and pull requests welcome. The rule for new tools: read-only, one documented stampchain.io endpoint per tool, and a docstring that says what the numbers mean and where they fall short. If a stampchain.io endpoint misbehaves, file it upstream at [stampchain-io/stampchain.io](https://github.com/stampchain-io/stampchain.io/issues) and link it here.

## Related

- [stampchain.io](https://github.com/stampchain-io/stampchain.io) — the explorer and API this server wraps (AGPL-3.0, separate project)
- [btc_stamps](https://github.com/stampchain-io/btc_stamps) — the Bitcoin Stamps indexer
- [Bitcoin Stamps protocol docs](https://bitcoinstamps.xyz)

Built by [sailorpepe](https://github.com/sailorpepe) for the stampchain.io community. MIT.