io.github.ExpertVagabond/ordinals

Official registry Other

Bitcoin Ordinals MCP Server — inscriptions, runes, BRC-20, collections & rare sats

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package ordinals-mcp

Claude Code

claude mcp add ordinals -e 'HIRO_API_KEY=<your hiro_api_key>' -e 'ORDISCAN_API_KEY=<your ordiscan_api_key>' -e 'MAGIC_EDEN_API_KEY=<your magic_eden_api_key>' -- npx -y ordinals-mcp@0.1.2

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "ordinals": {
            "command": "npx",
            "args": [
                "-y",
                "ordinals-mcp@0.1.2"
            ],
            "env": {
                "HIRO_API_KEY": "<your hiro_api_key>",
                "ORDISCAN_API_KEY": "<your ordiscan_api_key>",
                "MAGIC_EDEN_API_KEY": "<your magic_eden_api_key>"
            }
        }
    }
}

Environment variables

HIRO_API_KEY secret Hiro API key (free at platform.hiro.so) — 500 RPM
ORDISCAN_API_KEY secret Ordiscan API key (free at ordiscan.com/docs/api)
MAGIC_EDEN_API_KEY secret Magic Eden API key (optional, higher rate limits)

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents

ordinals-mcp
Install
Configure
Tools (24)
Why This One?
Architecture
Environment Variables
Development
License

ordinals-mcp

The most complete Bitcoin Ordinals MCP server. 24 tools covering inscriptions, runes, BRC-20 tokens, collections, rare sats, and marketplace data. Aggregates Hiro, Ordiscan, and Magic Eden APIs with intelligent caching and automatic failover.

The only alternative (ordiscan-mcp) has 25 npm downloads and covers a fraction of the surface. This server is the production-grade option.

Install

npx ordinals-mcp@latest

Or install globally:

npm install -g ordinals-mcp
ordinals-mcp

Configure

Add to your MCP config (claude_desktop_config.json or ~/.mcp.json):

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

At least one of HIRO_API_KEY or ORDISCAN_API_KEY is required. Both are free:

Provider	Rate Limit	Get Key
Hiro (primary)	500 RPM	platform.hiro.so
Ordiscan (fallback)	--	ordiscan.com/docs/api
Magic Eden (optional)	--	docs.magiceden.io

Tools (24)

Inscriptions (5)

Tool	Description	Key Params
`get_inscription`	Full inscription details by ID or number	`id`
`search_inscriptions`	Search inscriptions with filters (type, mime, date range)	`query`, `filters`
`get_inscription_content`	Raw content of an inscription	`id`
`get_inscription_transfers`	Transfer history for an inscription	`id`
`get_inscription_traits`	Traits and attributes of an inscription	`id`

Address Queries (4)

Tool	Description	Key Params
`get_address_inscriptions`	All inscriptions held by a Bitcoin address	`address`
`get_brc20_balances`	BRC-20 token balances for an address	`address`
`get_rune_balances`	Rune balances for an address	`address`
`get_address_rare_sats`	Rare satoshis held by an address	`address`

Runes (6)

Tool	Description	Key Params
`get_rune_info`	Detailed rune metadata (etching, supply, holders)	`rune`
`list_runes`	List all runes with pagination and sorting	`offset`, `limit`
`get_rune_holders`	Top holders of a specific rune	`rune`
`get_rune_activity`	Recent activity (mints, transfers, burns) for a rune	`rune`
`get_rune_market_info`	Market data -- floor price, volume, listings	`rune`
`get_rune_unlock_date`	Unlock/availability date for time-locked runes	`rune`

BRC-20 (3)

Tool	Description	Key Params
`get_brc20_token`	Token details (supply, limit, holders, deploy info)	`ticker`
`get_brc20_activity`	Recent activity for a BRC-20 token	`ticker`
`get_brc20_holders`	Top holders of a BRC-20 token	`ticker`

Collections (3)

Tool	Description	Key Params
`get_collection_info`	Collection metadata, floor price, volume	`slug`
`get_collection_inscriptions`	Inscriptions within a collection	`slug`
`get_collection_listings`	Active marketplace listings for a collection	`slug`

Sats & Transactions (3)

Tool	Description	Key Params
`get_sat_info`	Sat rarity, name, and inscription history	`sat_number`
`get_tx_inscriptions`	Inscriptions in a Bitcoin transaction	`txid`
`get_tx_runes`	Rune operations in a Bitcoin transaction	`txid`

Why This One?

24 tools, full coverage. Inscriptions, runes, BRC-20, collections, rare sats, and marketplace data. No other Ordinals MCP covers all six categories.
Multi-API with automatic failover. Aggregates Hiro (primary, 500 RPM), Ordiscan (fallback), and Magic Eden (marketplace). If one API rate-limits, requests automatically route to the next.
Intelligent caching. TTLs tuned per data type -- sat rarity (24h), inscription metadata (5m), collection info (2m), balances (1m), marketplace listings (30s). Stale cache serves as last resort during outages.

Architecture

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)

Environment Variables

Variable	Required	Description
`HIRO_API_KEY`	Yes*	Hiro API key (free)
`ORDISCAN_API_KEY`	Yes*	Ordiscan API key (free)
`MAGIC_EDEN_API_KEY`	No	Higher marketplace rate limits
`CACHE_TTL_SECONDS`	No	Default cache TTL (default: 300)

*At least one required.

Development

git clone https://github.com/ExpertVagabond/ordinals-mcp.git
cd ordinals-mcp
npm install
npm run build
npm run inspector    # MCP Inspector for testing

License

MIT -- Purple Squirrel Media

Frequently asked questions

What is io.github.ExpertVagabond/ordinals?

Bitcoin Ordinals MCP Server — inscriptions, runes, BRC-20, collections & rare sats

How do I install io.github.ExpertVagabond/ordinals?

It runs on your machine. In Claude Code: claude mcp add ordinals -e 'HIRO_API_KEY=<your hiro_api_key>' -e 'ORDISCAN_API_KEY=<your ordiscan_api_key>' -e 'MAGIC_EDEN_API_KEY=<your magic_eden_api_key>' -- npx -y ordinals-mcp@0.1.2. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.ExpertVagabond/ordinals need an API key?

Yes. It expects HIRO_API_KEY, ORDISCAN_API_KEY, MAGIC_EDEN_API_KEY, which you set in its configuration.

Is io.github.ExpertVagabond/ordinals open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.ExpertVagabond/ordinals?

It is published by ExpertVagabond. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.

Server details

Listed in: Official MCP Registry
Publisher: ExpertVagabond
Category: Other
Runs: Local
GitHub stars: ★ 2
License: MIT
Language: TypeScript
Last commit: Sep 13, 2026
Open issues: 2
Version: 0.1.2
Published: Feb 14, 2026

io.github.ExpertVagabond/ordinals

Similar servers

Canli Fundamentals SEC fundamentals point in time: first reported, known as of a date, every restatement.
arr-mcp One server, 40 tools, the whole media stack: *arrs, Jellyfin, Plex, Seerr, Cleanuparr, ...
Binggio Governed answers from your data: approved meanings only, refusals instead of guesses.
Cazimi: retrograde planets Retrograde stations, shadows and cazimi for Mercury to Pluto, to the minute UTC, from J...
Borgo Compare cities to live in on open, sourced data: take-home pay, rent, visas, climate, s...
Lviv Public Transport Lviv public transport MCP: stops, timetables, routes, and live vehicle positions. No AP...
Apple Safari Read and act on Safari — history, tabs and reading list, writes off by default
Geoproje Geotechnical and earthquake engineering tools: soil studies, SelectEQ, GMPS, GeoWave, O...

Other