Ordinals

io.github.ExpertVagabondPublished by GitHub account ExpertVagabondv0.1.2Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyFinanceData & Analytics

Overview

AI-generated overview

Bitcoin Ordinals MCP server that lets an assistant look up inscriptions, runes, BRC-20 tokens, collections, rare sats and marketplace data.

What you can do
  • Look up inscriptions by ID or number, search them with filters, and read content, transfer history and traits
  • Check what a Bitcoin address holds: inscriptions, BRC-20 balances, rune balances and rare sats
  • Browse runes: metadata, listings, holders, activity, market data and unlock dates
  • Inspect BRC-20 tokens and collections, including token details, holders, activity, floor price and active listings
  • Examine individual sats and transactions for rarity, inscription history and rune operations
When to use it
Useful when you want an assistant to research Bitcoin Ordinals, runes or BRC-20 assets, check what a given address holds, or pull collection and marketplace figures without leaving the chat.
Requirements
Runs locally via npx or a global npm install (Node.js). At least one of HIRO_API_KEY or ORDISCAN_API_KEY is required; MAGIC_EDEN_API_KEY is optional for higher marketplace rate limits. Optional CACHE_TTL_SECONDS. Network access to the Hiro, Ordiscan and Magic Eden APIs.
Before you install
Requires API keys stored in the MCP config env block (HIRO_API_KEY, ORDISCAN_API_KEY, optionally MAGIC_EDEN_API_KEY); keep them out of shared configs. Queries and addresses are sent to third-party APIs (Hiro, Ordiscan, Magic Eden). Tools are read-only lookups, but cached data can be stale during outages.

Installation

In SourceWeft

  1. Open Ordinals in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

ordinals-mcp

[npm version] [License: MIT] [Node] [Tools]

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

bash
npx ordinals-mcp@latest

Or install globally:

bash
npm install -g ordinals-mcpordinals-mcp

Configure

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

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:

ProviderRate LimitGet Key
Hiro (primary)500 RPMplatform.hiro.so
Ordiscan (fallback)--ordiscan.com/docs/api
Magic Eden (optional)--docs.magiceden.io

Tools (24)

Inscriptions (5)

ToolDescriptionKey Params
get_inscriptionFull inscription details by ID or numberid
search_inscriptionsSearch inscriptions with filters (type, mime, date range)query, filters
get_inscription_contentRaw content of an inscriptionid
get_inscription_transfersTransfer history for an inscriptionid
get_inscription_traitsTraits and attributes of an inscriptionid

Address Queries (4)

ToolDescriptionKey Params
get_address_inscriptionsAll inscriptions held by a Bitcoin addressaddress
get_brc20_balancesBRC-20 token balances for an addressaddress
get_rune_balancesRune balances for an addressaddress
get_address_rare_satsRare satoshis held by an addressaddress

Runes (6)

ToolDescriptionKey Params
get_rune_infoDetailed rune metadata (etching, supply, holders)rune
list_runesList all runes with pagination and sortingoffset, limit
get_rune_holdersTop holders of a specific runerune
get_rune_activityRecent activity (mints, transfers, burns) for a runerune
get_rune_market_infoMarket data -- floor price, volume, listingsrune
get_rune_unlock_dateUnlock/availability date for time-locked runesrune

BRC-20 (3)

ToolDescriptionKey Params
get_brc20_tokenToken details (supply, limit, holders, deploy info)ticker
get_brc20_activityRecent activity for a BRC-20 tokenticker
get_brc20_holdersTop holders of a BRC-20 tokenticker

Collections (3)

ToolDescriptionKey Params
get_collection_infoCollection metadata, floor price, volumeslug
get_collection_inscriptionsInscriptions within a collectionslug
get_collection_listingsActive marketplace listings for a collectionslug

Sats & Transactions (3)

ToolDescriptionKey Params
get_sat_infoSat rarity, name, and inscription historysat_number
get_tx_inscriptionsInscriptions in a Bitcoin transactiontxid
get_tx_runesRune operations in a Bitcoin transactiontxid

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

VariableRequiredDescription
HIRO_API_KEYYes*Hiro API key (free)
ORDISCAN_API_KEYYes*Ordiscan API key (free)
MAGIC_EDEN_API_KEYNoHigher marketplace rate limits
CACHE_TTL_SECONDSNoDefault cache TTL (default: 300)

*At least one required.

Development

bash
git clone https://github.com/ExpertVagabond/ordinals-mcp.gitcd ordinals-mcpnpm installnpm run buildnpm run inspector    # MCP Inspector for testing

License

MIT -- Purple Squirrel Media

Source: README.md at commit ec7e8cb

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts