ordinals

ordinals-mcp

最全面的 Bitcoin Ordinals MCP 服务。 提供 24 个工具，涵盖铭文、符文、BRC-20 代币、合集、稀有聪和市场数据。聚合 Hiro、Ordiscan 和 Magic Eden API，并提供智能缓存和自动故障切换。

唯一的替代方案（ordiscan-mcp）在 npm 上仅有 25 次下载，覆盖的功能也只是其中一小部分。本服务是适用于生产环境的选择。

安装

npx ordinals-mcp@latest

也可以全局安装：

npm install -g ordinals-mcp
ordinals-mcp

配置

添加到你的 MCP 配置（claude_desktop_config.json 或 ~/.mcp.json）中：

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

至少需要 HIRO_API_KEY 或 ORDISCAN_API_KEY 其中之一。两者都可以免费获取：

提供方	速率限制	获取密钥
Hiro（主要）	500 RPM	platform.hiro.so
Ordiscan（备用）	--	ordiscan.com/docs/api
Magic Eden（可选）	--	docs.magiceden.io

工具（24 个）

铭文（5 个）

工具	描述	关键参数
get_inscription	按 ID 或编号获取完整铭文详情	id
search_inscriptions	使用筛选条件（类型、MIME、日期范围）搜索铭文	query, filters
get_inscription_content	获取铭文的原始内容	id
get_inscription_transfers	获取铭文的转移历史	id
get_inscription_traits	获取铭文的特征和属性	id

地址查询（4 个）

工具	描述	关键参数
get_address_inscriptions	获取 Bitcoin 地址持有的所有铭文	address
get_brc20_balances	获取地址的 BRC-20 代币余额	address
get_rune_balances	获取地址的符文余额	address
get_address_rare_sats	获取地址持有的稀有聪	address

符文（6 个）

工具	描述	关键参数
get_rune_info	获取详细的符文元数据（铭刻、供应量、持有者）	rune
list_runes	分页并排序列出所有符文	offset, limit
get_rune_holders	获取特定符文的顶级持有者	rune
get_rune_activity	获取符文的近期活动（铸造、转移、销毁）	rune
get_rune_market_info	获取市场数据——地板价、交易量、挂单	rune
get_rune_unlock_date	获取时间锁定符文的解锁／可用日期	rune

BRC-20（3 个）

工具	描述	关键参数
get_brc20_token	获取代币详情（供应量、限额、持有者、部署信息）	ticker
get_brc20_activity	获取 BRC-20 代币的近期活动	ticker
get_brc20_holders	获取 BRC-20 代币的顶级持有者	ticker

合集（3 个）

工具	描述	关键参数
get_collection_info	获取合集元数据、地板价和交易量	slug
get_collection_inscriptions	获取合集中的铭文	slug
get_collection_listings	获取合集在市场上的活跃挂单	slug

聪与交易（3 个）

工具	描述	关键参数
get_sat_info	获取聪的稀有度、名称和铭文历史	sat_number
get_tx_inscriptions	获取 Bitcoin 交易中的铭文	txid
get_tx_runes	获取 Bitcoin 交易中的符文操作	txid

为什么选择这个？

• 24 个工具，全面覆盖。 铭文、符文、BRC-20、合集、稀有 sat 和市场数据。没有其他 Ordinals MCP 涵盖全部六个类别。
• 多 API 自动故障转移。 整合 Hiro（主要 API，500 RPM）、Ordiscan（备用）和 Magic Eden（市场）。如果某个 API 达到速率限制，请求会自动转发到下一个 API。
• 智能缓存。 根据数据类型调整 TTL——sat 稀有度（24 小时）、铭文元数据（5 分钟）、合集信息（2 分钟）、余额（1 分钟）、市场列表（30 秒）。服务中断时，过期缓存可作为最后的备用数据源。

架构

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)

环境变量

变量	必需	描述
HIRO_API_KEY	是*	Hiro API 密钥（免费）
ORDISCAN_API_KEY	是*	Ordiscan API 密钥（免费）
MAGIC_EDEN_API_KEY	否	提高市场速率限制
CACHE_TTL_SECONDS	否	默认缓存 TTL（默认：300）

*至少需要一个。

开发

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

许可证

MIT —— Purple Squirrel Media