{
  "markdown": "# ordinals-mcp\n\n[![npm version](https://img.shields.io/npm/v/ordinals-mcp)](https://www.npmjs.com/package/ordinals-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node](https://img.shields.io/badge/Node-%3E%3D18-339933?logo=node.js)](https://nodejs.org)\n[![Tools](https://img.shields.io/badge/tools-24-blue)](https://modelcontextprotocol.io)\n\n**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.\n\nThe only alternative (ordiscan-mcp) has 25 npm downloads and covers a fraction of the surface. This server is the production-grade option.\n\n## Install\n\n```bash\nnpx ordinals-mcp@latest\n```\n\nOr install globally:\n\n```bash\nnpm install -g ordinals-mcp\nordinals-mcp\n```\n\n## Configure\n\nAdd to your MCP config (`claude_desktop_config.json` or `~/.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"ordinals\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"ordinals-mcp@latest\"],\n      \"env\": {\n        \"HIRO_API_KEY\": \"your-key\",\n        \"ORDISCAN_API_KEY\": \"your-key\"\n      }\n    }\n  }\n}\n```\n\nAt least one of `HIRO_API_KEY` or `ORDISCAN_API_KEY` is required. Both are free:\n\n| Provider | Rate Limit | Get Key |\n|----------|-----------|---------|\n| **Hiro** (primary) | 500 RPM | [platform.hiro.so](https://platform.hiro.so) |\n| **Ordiscan** (fallback) | -- | [ordiscan.com/docs/api](https://ordiscan.com/docs/api) |\n| **Magic Eden** (optional) | -- | [docs.magiceden.io](https://docs.magiceden.io) |\n\n## Tools (24)\n\n### Inscriptions (5)\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `get_inscription` | Full inscription details by ID or number | `id` |\n| `search_inscriptions` | Search inscriptions with filters (type, mime, date range) | `query`, `filters` |\n| `get_inscription_content` | Raw content of an inscription | `id` |\n| `get_inscription_transfers` | Transfer history for an inscription | `id` |\n| `get_inscription_traits` | Traits and attributes of an inscription | `id` |\n\n### Address Queries (4)\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `get_address_inscriptions` | All inscriptions held by a Bitcoin address | `address` |\n| `get_brc20_balances` | BRC-20 token balances for an address | `address` |\n| `get_rune_balances` | Rune balances for an address | `address` |\n| `get_address_rare_sats` | Rare satoshis held by an address | `address` |\n\n### Runes (6)\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `get_rune_info` | Detailed rune metadata (etching, supply, holders) | `rune` |\n| `list_runes` | List all runes with pagination and sorting | `offset`, `limit` |\n| `get_rune_holders` | Top holders of a specific rune | `rune` |\n| `get_rune_activity` | Recent activity (mints, transfers, burns) for a rune | `rune` |\n| `get_rune_market_info` | Market data -- floor price, volume, listings | `rune` |\n| `get_rune_unlock_date` | Unlock/availability date for time-locked runes | `rune` |\n\n### BRC-20 (3)\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `get_brc20_token` | Token details (supply, limit, holders, deploy info) | `ticker` |\n| `get_brc20_activity` | Recent activity for a BRC-20 token | `ticker` |\n| `get_brc20_holders` | Top holders of a BRC-20 token | `ticker` |\n\n### Collections (3)\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `get_collection_info` | Collection metadata, floor price, volume | `slug` |\n| `get_collection_inscriptions` | Inscriptions within a collection | `slug` |\n| `get_collection_listings` | Active marketplace listings for a collection | `slug` |\n\n### Sats & Transactions (3)\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `get_sat_info` | Sat rarity, name, and inscription history | `sat_number` |\n| `get_tx_inscriptions` | Inscriptions in a Bitcoin transaction | `txid` |\n| `get_tx_runes` | Rune operations in a Bitcoin transaction | `txid` |\n\n## Why This One?\n\n- **24 tools, full coverage.** Inscriptions, runes, BRC-20, collections, rare sats, and marketplace data. No other Ordinals MCP covers all six categories.\n- **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.\n- **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.\n\n## Architecture\n\n```\nRequest --> Cache (TTL + ETag)\n  |--> HIT: return cached\n  |--> MISS:\n      |--> Hiro (primary, 500 RPM)\n      |     |--> Success: cache + return\n      |     |--> Rate limited: Ordiscan (fallback) --> Stale cache (last resort)\n      |--> Magic Eden (marketplace-specific)\n```\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `HIRO_API_KEY` | Yes* | Hiro API key ([free](https://platform.hiro.so)) |\n| `ORDISCAN_API_KEY` | Yes* | Ordiscan API key ([free](https://ordiscan.com/docs/api)) |\n| `MAGIC_EDEN_API_KEY` | No | Higher marketplace rate limits |\n| `CACHE_TTL_SECONDS` | No | Default cache TTL (default: 300) |\n\n*At least one required.\n\n## Development\n\n```bash\ngit clone https://github.com/ExpertVagabond/ordinals-mcp.git\ncd ordinals-mcp\nnpm install\nnpm run build\nnpm run inspector    # MCP Inspector for testing\n```\n\n## License\n\nMIT -- [Purple Squirrel Media](https://github.com/ExpertVagabond)\n",
  "bytes": 5676,
  "sha": "60a9605170d7afddbb333022ded57bb5a2a46ea04318e65b9cbbe146666945af",
  "repo_slug": "expertvagabond/ordinals-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_expertvagabond_ordinals_0df426f1/readme"
}