bitmap-mcp

bitmap-mcp

Live Bitcoin, Ordinals, Runes, and Bitmap data for any AI agent — over the Model Context Protocol.

bitmap-mcp is a read-only MCP server that lets AI agents (Claude Desktop, Cursor, Claude Code, and anything else that speaks MCP) resolve Bitcoin on-chain facts in real time: a Bitmap district, an Ordinals inscription, a Rune, a sat, a block, and current fees.

Zero config. No API key. No Bitcoin node. Just npx bitmap-mcp.

npx bitmap-mcp

Why

Agents can already reason about Bitcoin in the abstract, but they cannot look anything up natively. Ask an agent "who owns Bitmap district 840000?" or "what is the current supply of DOG GO TO THE MOON?" and it has no tool to answer — it guesses or refuses.

There is no MCP server today that natively resolves a Bitmap district, an inscription, or a rune. bitmap-mcp fills that gap with a tiny, dependency-light, read-only tool surface backed entirely by free public APIs.

Quick start

Run it directly:

npx bitmap-mcp

The server speaks MCP over stdio, so you wire it into your agent's config and the agent launches it for you.

Claude Desktop

Add this to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "bitmap": {
      "command": "npx",
      "args": ["-y", "bitmap-mcp"]
    }
  }
}

Cursor

Add this to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "bitmap": {
      "command": "npx",
      "args": ["-y", "bitmap-mcp"]
    }
  }
}

Claude Code

claude mcp add bitmap -- npx -y bitmap-mcp

Restart your client after editing its config. The agent now has six new Bitcoin tools.

Tools

Tool	Arguments	Returns
get_bitmap	district: number	The claiming inscription id, owner address, sat, content type, and current location for a Bitmap district (a block height).
get_inscription	id: string	An Ordinals inscription's content type, owner, sat, genesis height, current location, and content URL.
get_rune	name: string	A Rune's supply, divisibility, holder count, mint status, market cap, floor price, and verification.
get_fees	(none)	Current recommended fee estimates in sat/vB (fastest, half hour, hour, economy, minimum).
get_block	height?: number	A block summary: hash, timestamp, transaction count, size, weight, difficulty. Omit height for the chain tip.
resolve_sat	sat: number	A sat's Rodarmor rarity, the block it was minted in, and its current inscription/owner if inscribed.

Rune names work with or without bullet separators: DOG•GO•TO•THE•MOON and DOGGOTOTHEMOON both resolve.

Example agent prompts

Once the server is wired in, you can ask your agent things like:

• "Use the bitmap tools to tell me who owns Bitmap district 840000 and what the inscription number is."
• "What is the current circulating supply and holder count of the rune DOG GO TO THE MOON?"
• "What are Bitcoin fees right now, and how big was the latest block?"
• "Is sat 1252201400444387 rare, and is anything inscribed on it?"

How it works

bitmap-mcp is read-only and keyless. It never holds funds, never signs anything, and never needs a wallet. Every tool is a thin, typed wrapper over a free public API:

Tool	Data source
get_fees, get_block	mempool.space
get_inscription, resolve_sat	the reference ord server recursive API at ordinals.com
get_rune	the keyless Magic Eden Ordinals API
get_bitmap	the TRAC public Bitmap indexer (primary) with a Magic Eden fallback, enriched with ord metadata

Design choices:

• No node required. All data comes over HTTPS from public indexers.
• No API key. Nothing to sign up for; just run it.
• Graceful failure. If an upstream API is briefly unavailable, the tool returns a clean error message — it never crashes the server or the agent session.
• Sat rarity is computed locally from Bitcoin's subsidy schedule (ordinal theory), so it is correct and instant; only the current location of an inscribed sat needs the network.
• Minimal dependencies. Just the MCP SDK and zod. The Bitmap indexer is reached over its Socket.IO protocol using the built-in fetch, with no extra websocket dependency.

A bitmap district is a Bitcoin block claimed by the first valid <height>.bitmap inscription; its owner owns the district. See the Bitmap theory handbook for background.

Development

git clone https://github.com/BitmapAsset/bitmap-mcp.git
cd bitmap-mcp
npm install
npm run build      # compile TypeScript to dist/
npm test           # offline unit tests
npm run test:live  # live smoke tests against real APIs (network required)
npm run dev        # run the server from source with tsx

Contributing

Issues and pull requests are welcome. Good first contributions:

• Add a tool (for example BRC-20 token info, address holdings, or parcel lookup).
• Add or swap a data provider with better uptime.
• Expand the test suite.

Please keep the project read-only, keyless, and dependency-light. No tool should ever require a private key, a wallet, or a paid API.

License

MIT © 2026 Gravity (BitmapAsset). See LICENSE.