Skip to main content
Glama
Bitcoin Stamps MCP

Bitcoin Stamps MCP

Bitcoin Stamps MCP

A Model Context Protocol server for Bitcoin Stamps — 24 read-only tools over the stampchain.io explorer API, for any AI agent.

PyPI Python MCP Keys License: MIT

Status (2026-09-15): this Python server was the prototype. The work is going into the official stampchain-io/stampchain-mcp instead — first PR: #6, align tools with the live v2 API; 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 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

pip install stampchain-mcp

Claude Desktop — add to claude_desktop_config.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?"

Related MCP server: Lighthouse Explorer MCP Server

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). 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

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

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 and link it here.

Built by sailorpepe for the stampchain.io community. MIT.

Available Tools

24 tools
dispensers_by_addressDispensers By AddressA

All dispensers a Bitcoin address has opened, optionally filtered by status (open / closed). Useful to see what a seller currently lists.

Inputs: address (required), page, limit, status. Returns: result

get_blockGet BlockA

A Bitcoin block as the Stamps indexer sees it. block = block index (height) or block hash; leave it empty and set last (1-50) to get the most recent N blocks instead. Returns block_time, hashes, tx_count.

Inputs: last, block. Returns: result

get_collectionGet CollectionA

One collection by id (hex) or by name, with its stamps and — when include_market_data — floor price, volume and holder metrics.

Inputs: collection (required), include_market_data. Returns: result

get_src20Get Src20A

Everything about one SRC-20 token in one call: the DEPLOY record (max supply, per-mint limit, decimals, creator, block), mint status (total_minted, progress %, total_mints, holders), and market data (price in BTC/USD, market cap, 24h volume, 24h/7d/30d change, primary exchange, data_quality_score). 7d/30d/total volume are often 0 or null — the upstream exchanges do not publish them; do not read a zero there as 'no trading'.

Inputs: tick (required). Returns: result

get_stampGet StampA

One stamp by number, tx hash, or CPID: creator (+ creator_name if registered), supply, locked/divisible flags, mimetype, file hash and size, block and time, stamp_url (the rendered artwork), plus market_data and lowestPriceDispenser when the indexer has them. The base64 image payload is dropped unless include_image_base64=True.

Inputs: stamp_id (required), include_image_base64. Returns: result

list_collectionsList CollectionsD

Stamp collections: id, name, description, creators, stamp numbers, stamp_count, total_editions.

Inputs: page, limit. Returns: result

list_src20_deploysList Src20 DeploysA

Recent SRC-20 DEPLOY transactions (newest first): tick, max, lim, decimals, creator, block and time, deploy stamp URL. For a ranked market view use src20_market; for mint progress use get_src20.

Inputs: page, limit. Returns: result

list_stampsList StampsA

Paginated stamps, newest first by default (sort DESC/ASC by stamp number). Optional market filters apply to stamps that have market data (floor price in BTC from open dispensers, holder count, 24h volume, data_quality_score 0-10). Each row carries ident (STAMP, SRC-20, SRC-721) so a client can filter by protocol.

Inputs: page, sort, limit, min_volume_24h, +4 more. Returns: result

search_src20Search Src20A

Search SRC-20 tokens by tick fragment. Returns tick, deploy tx, max_supply, total_minted, progress (%), holders, total_mints, and the per-mint limit. mintable_only=True keeps tokens still under 100%.

Inputs: q (required), mintable_only. Returns: result

search_stampsSearch StampsA

Search stamps by free text (creator name, CPID / asset name such as NAMEDPEPE, stamp number, tx hash fragment). Returns stamp number, CPID, preview URL, mimetype, creator, tx hash. Negative stamp numbers are 'cursed' stamps (pre-protocol-rule artifacts, still indexed).

Inputs: q (required). Returns: result

src101_deploysSrc101 DeploysC

SRC-101 deployments — the name-service roots (e.g. BitNameService 'btc' names). Each row: deploy tx hash, root/tick, name, pricing tiers (pri), mint limits, image base URL, creator.

Inputs: page, limit. Returns: result

src101_walletSrc101 WalletA

SRC-101 names (Bitcoin Name Service tokens) held by an address. With deploy_hash: names under that specific root (primary name first). Without: every SRC-101 balance the indexer has for the address.

Inputs: address (required), deploy_hash. Returns: result

src20_balanceSrc20 BalanceA

SRC-20 token balances of a Bitcoin address — all ticks, or one tick when given. Amounts are token units (see the deploy's decimals).

Inputs: address (required), page, tick, limit. Returns: result

src20_holdersSrc20 HoldersA

Holder snapshot for an SRC-20 tick at the current block: address and amount, largest first. Use for concentration checks (top-10 share).

Inputs: tick (required), page, limit. Returns: result

src20_marketSrc20 MarketA

SRC-20 market data. With tick: that token. Without: a ranked list (sort: market_cap_usd | volume_24h_btc | price_change_24h_percent; order asc/desc). Fields: price BTC/USD, floor (from dispensers), market cap, 24h volume, holder count, circulating supply, 24h/7d/30d change, primary exchange, exchange sources, data_quality_score (0-10), last_updated. Multi-period volumes are unreliable upstream (often 0).

Inputs: page, sort, tick, limit, +1 more. Returns: result

src20_transactionsSrc20 TransactionsA

Valid SRC-20 transactions (DEPLOY / MINT / TRANSFER), newest first. Filter by tick, by op, and/or by block_index. Rows carry creator, destination, amt, tick, stamp number, block_time.

Inputs: op, page, tick, limit, +1 more. Returns: result

src20_txSrc20 TxA

Decode one SRC-20 transaction by its Bitcoin tx hash: op, tick, amounts, creator, destination, validity, block.

Inputs: tx_hash (required). Returns: result

stamp_activityStamp ActivityA

Transfer history for a stamp. kind='sends' = Counterparty sends (owner to owner); kind='dispenses' = purchases from dispensers (with the BTC paid). Newest first.

Inputs: stamp_id (required), kind, page, limit. Returns: result

stampchain_healthStampchain HealthA

Health of stampchain.io and its indexer: API/DB/mempool/XCP status, indexed vs network block height (isSynced), total stamps and SRC-20 deployments, circuit-breaker state. Call first if other tools error.

Inputs: no named parameters. Returns: result

stamp_dispensersStamp DispensersB

Counterparty dispensers for a stamp — the on-chain 'listings'. Each row: source/origin address, give_quantity, give_remaining, escrow_quantity, satoshirate and btcrate (price per unit), status (open/closed), tx hash. An open dispenser with give_remaining > 0 is a live offer; the lowest btcrate among them is the floor. Buying is a wallet action by the user — this tool only reads.

Inputs: stamp_id (required), page, limit. Returns: result

stamp_holdersStamp HoldersC

Who holds a stamp: address, amount held, percentage of supply. Supply for most art stamps is 1; SRC-721 and editioned stamps spread across many holders.

Inputs: stamp_id (required), page, limit. Returns: result

stamps_in_blockStamps In BlockA

Stamps minted in a block — the latest indexed block when block_index is omitted. Good for 'what just got stamped'.

Inputs: block_index. Returns: result

wallet_balanceWallet BalanceB

Combined view of a Bitcoin address: its BTC balance, stamps held (with UTXO binding info) and SRC-20 token balances, in one call.

Inputs: address (required), page, limit. Returns: result

wallet_stampsWallet StampsB

Stamps held by a Bitcoin address, with per-stamp balance and, when available, value (sort_by: DESC/ASC by stamp, value_desc, value_asc, quantity_desc, recent_desc ...). Enhanced with market data by default.

Inputs: address (required), page, limit, sort_by. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 24 tools

    Disambiguation3/5

    Some pairs overlap: get_src20 already includes market data, making src20_market with a tick largely redundant, and get_block/stamps_in_block both cover a block from different angles. However, most resource-specific tools are clearly separated by protocol and purpose.

    Naming Consistency3/5

    Names mix verb-first forms like get_block and list_stamps with noun-first resource forms like stamp_holders, src20_market, and wallet_balance, so there is no uniform verb_noun convention. The snake_case prefixes make the set readable and somewhat predictable, but the get/list/search verbs are applied inconsistently.

    Tool Count3/5

    24 tools falls in the heavy 16-25 band, though the server covers three protocols plus wallet, market, and collection data. Most tools have a distinct job, but a few could be consolidated without losing capability.

    Completeness5/5

    As a read-only indexer, the surface is comprehensive: stamp lookup/search/list, holders, dispensers, transfers, block data, wallet balances, SRC-20 lifecycle/market/holders/transactions, SRC-101 names, and collections are all represented. There are no obvious dead ends for querying the indexed data.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables interaction with Bitcoin Stamps data via the Stampchain API, providing tools for querying stamp information, collections, and blockchain data without requiring authentication.
      13
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides tools for AI assistants to query the Canton Network for data on contracts, governance, validators, and party transactions through the Lighthouse Explorer API. It enables seamless interaction with blockchain statistics, price history, and name services without requiring an API key.
      208 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Stamp, upgrade, and verify Bitcoin timestamps via AI agents using the OpenTimestamps protocol. No API keys required.
      9
      80 npm
      3
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Exposes 17 read-only tools from six XRPL-Utilities services so AI agents can access XRPL wallet analysis, signal feeds, macro telemetry, permissioned asset stacks, RWA tracking, and ETF flow data.
      41
      493 npm
      MIT