Skip to main content
Glama

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.


Related MCP server: Satstream MCP Server

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.

Available Tools

6 tools
get_bitmapResolve a Bitmap districtA

Resolve a Bitmap district number (a Bitcoin block height) to its claiming inscription id, owner address, and sat. A district N is owned by the first valid '.bitmap' inscription.

ParametersJSON Schema
NameRequiredDescriptionDefault
districtYesBitmap district number (a Bitcoin block height), e.g. 0 for the '0.bitmap' district.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the behavioral burden. It discloses the core ownership rule, 'a district N is owned by the first valid '<N>.bitmap' inscription', which informs the agent of the deterministic resolution. It does not mention edge cases like unresolved districts or that it is a read-only operation, but the verb 'resolve' suggests a safe lookup.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the main purpose, then the ownership rule. Every sentence adds value with no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description states the return items (inscription id, owner address, sat) and explains how the district is claimed. It lacks details on behavior for unclaimed districts, but for a simple lookup tool with a single parameter, this is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the parameter fully, describing district as a Bitcoin block height and enforcing a minimum of 0. The description adds a concrete example ('0 for the '0.bitmap' district') and links the parameter to the resolution rule, but no substantial new semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Resolve' and identifies the resource as 'a Bitmap district number (a Bitcoin block height)' and the output as 'claiming inscription id, owner address, and sat'. This clearly distinguishes it from sibling tools like resolve_sat or get_inscription, which address different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when you need to resolve a Bitmap district to its ownership info, use this tool. However, it does not explicitly mention when not to use it or mention alternative tools, so it falls short of explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_blockGet a Bitcoin block summaryA

Return a summary of a Bitcoin block (hash, timestamp, transaction count, size, weight, difficulty). Omit height for the current chain tip.

ParametersJSON Schema
NameRequiredDescriptionDefault
heightNoBlock height to summarize. Omit to get the current chain tip block.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It discloses what the summary includes and the special behavior when height is omitted. It does not mention error handling or explicitly confirm read-only semantics, but the read-only nature is strongly implied by 'summary' and the listed fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the purpose and immediately lists the output fields and the key behavioral nuance. There is no wasted wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, but the description enumerates the return fields, making the output explicit. It also explains the only behavioral nuance (chain tip when height omitted). For a simple one-parameter read tool, this is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage of the single parameter 'height' with a clear description. The tool description repeats the omit-for-tip behavior but adds no new semantic detail beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return') and resource ('a Bitcoin block') with a clear scope ('summary') listing the fields (hash, timestamp, transaction count, size, weight, difficulty). This clearly distinguishes get_block from sibling tools that address other Bitcoin entities (sat, bitmap, inscription, rune, fees).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: it summarizes a Bitcoin block and explains the omit-height behavior for the current chain tip. However, it does not explicitly mention alternatives or when not to use this tool, though sibling names make the distinction implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_feesGet Bitcoin fee estimatesA

Return current recommended Bitcoin transaction fee estimates in sat/vB (fastest, half hour, hour, economy, minimum).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It accurately indicates a read-only operation ('Return') and specifies output categories, but does not mention authentication, rate limits, or potential side effects. For this simple getter, this is adequate and provides full disclosure of the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded with the action and resource, no wasted words. It is concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fully specifies the return values (sat/vB with five categories), which is sufficient for a zero-param tool with no output schema. It doesn't need to explain parameters or side effects, making it complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and the schema coverage is 100% (vacuously). The description correctly focuses on the output rather than parameters, so it provides no additional parameter semantics needed. This aligns with the baseline for a tool with no parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Return') and identifies the exact resource ('Bitcoin transaction fee estimates') with units (sat/vB) and categories (fastest, half hour, hour, economy, minimum). This clearly distinguishes it from sibling tools that handle other Bitcoin data types like blocks, runes, or inscriptions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage—if you need current fee estimates, use this tool—but it does not explicitly state when to use it versus alternatives or mention exclusions. Sibling tools are about different resources, so context is clear, but explicit guidance is absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_inscriptionGet an Ordinals inscriptionA

Look up an Ordinals inscription by id and return its content type, owner address, sat, genesis height, current location, and content URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesInscription id, formatted as a 64-char txid followed by 'i' and an index, e.g. '6fb9...i0'.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavior. It states the tool returns specific fields, indicating a read-only retrieval, but does not address error cases, authentication, or side effects. The 'look up' verb implies safety, though not explicitly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that lists the action and all relevant return values. No wasted words, and the information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter lookup tool with no output schema, the description covers the purpose and return fields sufficiently. It lacks explicit differentiation guidance from sibling tools, but the resource-specific wording makes the tool's role clear within the family.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully documents the single 'id' parameter with format details. The description simply says 'by id' and adds no additional semantic meaning beyond the schema, so it stays at the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Look up' and clearly identifies the resource 'Ordinals inscription' by id, listing the returned fields (content type, owner address, sat, genesis height, current location, content URL). This distinguishes it from sibling tools like get_bitmap or get_fees.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for looking up inscription details by id, but provides no explicit when-to-use or alternative references. It doesn't mention when not to use this tool or suggest other tools for different scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_runeGet a RuneA

Look up a Rune by name (with or without bullet separators) and return supply, divisibility, holder count, mint status, and market data.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesRune name, with or without bullet separators, e.g. 'DOG•GO•TO•THE•MOON' or 'DOGGOTOTHEMOON'.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. 'Look up' implies a read-only operation, but the description does not disclose error behavior, not-found handling, or permission requirements. For a simple lookup, this level of transparency is minimal but acceptable; it neither misleads nor enriches.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that begins with the action ('Look up a Rune by name') and efficiently lists the return data. No redundant words, and the structure is immediately scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter lookup with no output schema and no annotations, the description covers the essential context: the input format flexibility and the specific output fields. It doesn't address error scenarios, but for a simple read tool with strong schema coverage, this is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% coverage for the 'name' parameter, including an explicit explanation and examples. The description merely reiterates the 'with or without bullet separators' detail, adding no new semantic meaning beyond the schema. Baseline 3 applies because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Look up a Rune by name' and lists specific return data (supply, divisibility, holder count, mint status, market data). This specific verb-resource pairing distinguishes it from sibling tools like get_bitmap, get_inscription, and get_block.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The context is clear: this tool is for looking up Rune by name, as opposed to other sibling lookups for sats, bitmaps, inscriptions, fees, or blocks. It doesn't explicitly state when not to use it or name alternatives, but the resource-specific wording and sibling names make the appropriate use case evident.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_satResolve a satA

Given a sat ordinal number, return its Rodarmor rarity (common, uncommon, rare, epic, legendary, mythic), the block it was minted in, and its current inscription/owner if inscribed.

ParametersJSON Schema
NameRequiredDescriptionDefault
satYesSat ordinal number (0 to 2099999997689999). Returns rarity and current inscription/owner if inscribed.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full transparency burden. It discloses the conditional 'if inscribed' behavior and specifies the return fields, which is valuable for a read-only lookup. However, it does not explicitly state error handling or that the operation is read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that clearly states the input and output. Every word earns its place, and there is no extraneous detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter tool with no output schema, the description lists the expected return fields, which gives sufficient context. It could include an example or field names, but given the low complexity, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter 'sat', so the baseline is 3. The description repeats the input meaning and adds output context, but the schema already documents the same information. No additional syntax or constraints are provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'resolve' with the resource 'sat' and clearly enumerates the exact outputs: Rodarmor rarity, mint block, and current inscription/owner if inscribed. This distinguishes it from sibling tools like get_block or get_inscription by focusing on sat ordinal properties.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clarifies what the tool does but stops short of explicitly stating when to use it over alternatives. It does not mention sibling tools or provide exclusions, though the intended use case is reasonably implied by the context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.1.0
    • First observedget_bitmap
    • First observedget_block
    • First observedget_fees
    • First observedget_inscription
    • First observedget_rune
    • First observedresolve_sat

TDQS

A4.2/5.0
Disambiguation5/5

Each tool targets a distinct entity or concept: sat ordinals, Bitmap districts, inscriptions, runes, fees, and blocks. There is no overlap or ambiguity between tool purposes.

Naming Consistency5/5

All tool names follow a uniform verb_noun snake_case pattern (resolve_sat, get_bitmap, get_inscription, get_rune, get_fees, get_block). The naming is fully consistent.

Tool Count5/5

Six tools is well within the ideal range and appropriate for a Bitcoin/Ordinals data server. Each tool covers a meaningful aspect without redundancy.

Completeness4/5

The tool set covers the core entities of the domain (sats, inscriptions, bitmaps, runes, blocks, fees), but lacks address-level or transaction-level lookups, which are common extensions for such a service. These gaps are minor and not severe.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    A Model Context Protocol server that enables querying Bitcoin blockchain data, including address information, transaction details, mempool statistics, and ordinals/runes data through the Satstream API.
    37
    MIT
  • F
    license
    A
    quality
    B
    maintenance
    A server that exposes blockchain data (balances, tokens, NFTs, contract metadata) via the Model Context Protocol, enabling AI agents and tools to access and analyze blockchain information contextually.
    18
    44
    -
  • A
    license
    B
    quality
    D
    maintenance
    A Model Context Protocol server that provides real-time Bitcoin blockchain and mempool data to AI clients, allowing access to comprehensive Bitcoin network information through various data tools.
    31
    26
    5
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/BitmapAsset/bitmap-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server