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

License

MIT

ordinals

Quick Install