# Ordinals Mcp

> Bitcoin Ordinals MCP server — 24 tools for inscriptions, runes, BRC-20, collections, marketplace data, and rare sats. Published on npm.

- **Type:** MCP server
- **Install:** `agentstack add mcp-expertvagabond-ordinals-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ExpertVagabond](https://agentstack.voostack.com/s/expertvagabond)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.2
- **License:** MIT
- **Upstream author:** [ExpertVagabond](https://github.com/ExpertVagabond)
- **Source:** https://github.com/ExpertVagabond/ordinals-mcp
- **Website:** - Creating gist ordinals-mcp-quickstart.md
✓ Created public gist ordinals-mcp-quickstart.md
https://gist.github.com/ExpertVagabond/bbb615fa0f72b7c397f7bd5cd004015f

## Install

```sh
agentstack add mcp-expertvagabond-ordinals-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ordinals-mcp

[](https://www.npmjs.com/package/ordinals-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)

**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-mcp
ordinals-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:

| Provider | Rate Limit | Get Key |
|----------|-----------|---------|
| **Hiro** (primary) | 500 RPM | [platform.hiro.so](https://platform.hiro.so) |
| **Ordiscan** (fallback) | -- | [ordiscan.com/docs/api](https://ordiscan.com/docs/api) |
| **Magic Eden** (optional) | -- | [docs.magiceden.io](https://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](https://platform.hiro.so)) |
| `ORDISCAN_API_KEY` | Yes* | Ordiscan API key ([free](https://ordiscan.com/docs/api)) |
| `MAGIC_EDEN_API_KEY` | No | Higher marketplace rate limits |
| `CACHE_TTL_SECONDS` | No | Default cache TTL (default: 300) |

*At least one required.

## Development

```bash
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](https://github.com/ExpertVagabond)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ExpertVagabond](https://github.com/ExpertVagabond)
- **Source:** [ExpertVagabond/ordinals-mcp](https://github.com/ExpertVagabond/ordinals-mcp)
- **License:** MIT
- **Homepage:** - Creating gist ordinals-mcp-quickstart.md
✓ Created public gist ordinals-mcp-quickstart.md
https://gist.github.com/ExpertVagabond/bbb615fa0f72b7c397f7bd5cd004015f

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.2 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.2** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-expertvagabond-ordinals-mcp
- Seller: https://agentstack.voostack.com/s/expertvagabond
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.