English Français العربية

io.github.ExpertVagabond/ordinals

السجل الرسمي أخرى

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

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

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 (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>"
            }
        }
    }
}

متغيرات البيئة

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

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. ordinals-mcp
  2. Install
  3. Configure
  4. Tools (24)
  5. Why This One?
  6. Architecture
  7. Environment Variables
  8. Development
  9. 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:

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

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

الأسئلة الشائعة

ما هو io.github.ExpertVagabond/ordinals؟

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

كيف أثبّت io.github.ExpertVagabond/ordinals؟

يعمل على جهازك. في 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 من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.ExpertVagabond/ordinals إلى مفتاح API؟

نعم. يتطلب HIRO_API_KEY, ORDISCAN_API_KEY, MAGIC_EDEN_API_KEY، وتضبطها في إعداداته.

هل io.github.ExpertVagabond/ordinals مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.ExpertVagabond/ordinals؟

ينشره ExpertVagabond. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.