ordinals-mcp

Bitcoin Ordinals MCP Server — multi-API access to inscriptions, runes, BRC-20 tokens, collections, marketplace data, and rare sats.

A Model Context Protocol server that gives AI models comprehensive access to the Bitcoin Ordinals ecosystem. Aggregates data from multiple APIs with built-in caching and rate limiting.

Quick Start

Claude Desktop / Claude Code

Add to your MCP config:

{
  "mcpServers": {
    "ordinals": {
      "command": "npx",
      "args": ["ordinals-mcp@latest"],
      "env": {
        "HIRO_API_KEY": "your-key",
        "ORDISCAN_API_KEY": "your-key"
      }
    }
  }
}

Get API Keys (free)

• Hiro (primary, 500 RPM): platform.hiro.so
• Ordiscan (secondary): ordiscan.com/docs/api
• Magic Eden (marketplace, optional): docs.magiceden.io

At least one of HIRO_API_KEY or ORDISCAN_API_KEY is required.

24 Tools

Inscriptions

Tool	Description
get_inscription	Get inscription metadata by ID or number
search_inscriptions	Search/filter inscriptions (address, mime type, rarity, block range)
get_inscription_content	Get raw inscription content (text, images, etc.)
get_inscription_transfers	Get transfer history for an inscription
get_inscription_traits	Get trait info for collection inscriptions

Address Lookups

Tool	Description
get_address_inscriptions	All inscriptions owned by an address
get_brc20_balances	BRC-20 token balances for an address
get_rune_balances	Rune balances for an address
get_address_rare_sats	Rare satoshis held by an address

Runes

Tool	Description
get_rune_info	Rune details (symbol, supply, mint terms)
list_runes	List all runes with pagination
get_rune_holders	Top holders of a rune
get_rune_activity	Recent mints, transfers, burns
get_rune_market_info	Price, market cap, 24h volume
get_rune_unlock_date	When a rune name becomes available

BRC-20

Tool	Description
get_brc20_token	Token details (supply, mint limit, decimals)
get_brc20_activity	Deploy, mint, transfer events
get_brc20_holders	Top holders of a BRC-20 token

Collections & Marketplace

Tool	Description
get_collection_info	Collection stats, floor price, volume
get_collection_inscriptions	List inscriptions in a collection
get_collection_listings	Active Magic Eden marketplace listings

Satoshis & Transactions

Tool	Description
get_sat_info	Sat rarity, epoch, inscriptions
get_tx_inscriptions	Inscriptions in a transaction
get_tx_runes	Rune transfers in a transaction

Architecture

Multi-API with Fallback

Request -> Cache (TTL + ETag)
  |-> HIT: return cached
  |-> MISS:
      |-> Hiro (primary, 500 RPM)
      |   |-> Success: cache + return
      |   |-> Rate limited:
      |       |-> Ordiscan (fallback)
      |       |-> Stale cache (last resort)
      |-> Magic Eden (marketplace-specific)

Built-in Rate Limiting

Per-API token bucket rate limiters with 80% safety margin. Automatic wait-and-retry when approaching limits.

Intelligent Caching

Data Type	TTL
Sat rarity	24 hours
Inscription metadata	5 minutes
Rune etching info	5 minutes
Collection info	2 minutes
Balances	1 minute
Marketplace listings	30 seconds

Environment Variables

Variable	Required	Description
HIRO_API_KEY	Yes*	Hiro API key (500 RPM)
ORDISCAN_API_KEY	Yes*	Ordiscan API key
MAGIC_EDEN_API_KEY	No	Higher marketplace rate limits
CACHE_TTL_SECONDS	No	Default cache TTL (default: 300)
RATE_LIMIT_BUFFER	No	Rate limit safety margin (default: 0.8)

*At least one API key is required.

Development

npm install
npm run build          # TypeScript + esbuild bundle
npm run watch          # TypeScript watch mode
npm run inspector      # MCP Inspector for testing

Links

• Website
• npm
• GitHub
• Setup Gist

License

MIT