# 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](https://modelcontextprotocol.io) 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`.

```bash
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:

```bash
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`):

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

### Cursor

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

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

### Claude Code

```bash
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](https://mempool.space/docs/api/rest) |
| `get_inscription`, `resolve_sat` | the reference [`ord` server recursive API](https://docs.ordinals.com/inscriptions/recursion.html) at `ordinals.com` |
| `get_rune` | the keyless [Magic Eden Ordinals API](https://docs.magiceden.io/) |
| `get_bitmap` | the [TRAC public Bitmap indexer](https://github.com/BennyTheDev/trac-bitmap-public-endpoint) (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](https://gitbook.bitmap.land/) for background.

---

## Development

```bash
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](./LICENSE).