Bitcoin Stamps MCP
Provides read-only access to Bitcoin Stamps data on the Bitcoin blockchain, including stamps, SRC-20 tokens and market data, SRC-101 names, collections, dispensers, and wallet balances via the stampchain.io explorer API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Bitcoin Stamps MCP What's the floor price on stamp 1?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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-mcpClaude 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 |
| Indexer sync state, block height, totals, circuit-breaker |
System |
| A block by height or hash, or the last N blocks |
Stamps |
| Free-text search: creator, CPID, stamp number, tx hash |
Stamps |
| Paginated stamps with market filters (floor, holders, volume, quality) |
Stamps |
| One stamp: creator, supply, mimetype, artwork URL, market data, lowest dispenser |
Stamps |
| Holders with amount and share of supply |
Stamps |
| Counterparty dispensers — the on-chain listings — with BTC rate and remaining |
Stamps |
| Everything a seller has listed, open or closed |
Stamps |
| Sends (owner to owner) or dispenses (purchases) for a stamp |
Stamps |
| What was stamped in a block, latest by default |
Wallets |
| Stamps an address holds, with value when known |
Wallets |
| BTC + stamps + SRC-20 for an address in one call |
SRC-20 |
| Tick search with mint progress and holders |
SRC-20 |
| Newest token deployments |
SRC-20 |
| Deploy + mint status + market data for one tick |
SRC-20 |
| Ranked market table, or one tick's prices, cap, volume, change |
SRC-20 |
| Token balances of an address, all ticks or one |
SRC-20 |
| Holder snapshot at the current block, largest first |
SRC-20 |
| DEPLOY / MINT / TRANSFER history by tick, op or block |
SRC-20 |
| Decode one SRC-20 transaction |
SRC-101 |
| Bitcoin Name Service roots and their pricing |
SRC-101 |
| Names an address holds |
Collections |
| Collections with stamp numbers and edition counts |
Collections |
| 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_btccomes from open Counterparty dispensers;nullmeans no open dispenser, not zero value.24-hour volume is reliable. 7-day, 30-day and all-time volume are frequently
0ornullbecause the upstream exchanges only publish 24h figures (stampchain.io#1100). Do not read a zero there as "no trading".data_quality_score(0–10) andprimary_exchange/exchange_sourcestell 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 |
|
| Point at |
| unset | Optional free API key sent as |
|
| Set |
|
| 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.
Related
stampchain.io — the explorer and API this server wraps (AGPL-3.0, separate project)
btc_stamps — the Bitcoin Stamps indexer
Built by sailorpepe for the stampchain.io community. MIT.
Available Tools
24 toolsdispensers_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
Scored across 24 tools
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.
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.
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.
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
Related MCP Connectors
Bitcoin RPC for AI agents. 7 read tools; x402 USDC on Base mainnet. Discovery is free.
Pay-per-call tools for AI agents, paid in USDC on Base or Solana. Web search, page and PDF reading, crypto news, Hyperliquid perps, market pulse, Chainlink price history, token checks, SEC filings, weather and more. Free calls every day, and a failed call costs nothing. Works with Tollkit Wallet.
Discover, inspect and run 63,000+ agent tools from one balance. Pay per call, no subscriptions.
Cheap on-chain lookups for agents, no API key: latest Ethereum block height, ERC-20 token balance, wallet balance (ETH + tokens), total token supply, decoded ERC-20 Transfer logs, address nonce, contract inspector and tx lookup on Ethereum and Base. Plus product price & availability from any product URL, URL to Markdown, page metadata, weather and crypto spot prices. Pay per call from $0.0005 in USDC on Base via x402.
Related MCP Servers
- AlicenseBqualityDmaintenanceA 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.13MIT
- AlicenseNot gradedqualityDmaintenanceProvides 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 npmMIT
- AlicenseAqualityBmaintenanceStamp, upgrade, and verify Bitcoin timestamps via AI agents using the OpenTimestamps protocol. No API keys required.980 npm3MIT
- AlicenseBqualityBmaintenanceExposes 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.41493 npmMIT