Skip to main content
Glama
solana-nft-mcp

solana-nft-mcp

by p1xelapp
README.md
<div align="center">

<img src="assets/banner.png" alt="solana-nft-mcp" width="100%" />

# solana-nft-mcp

**The NFT APIs I tried return an empty ownership history for a Metaplex Core asset, and an AI reading that empty answer tells you the card has never traded.** solana-nft-mcp reads the chain itself: who owned it, who can freeze it, what sold and for how much, and where the deals are. Read-only, no sign-up, nothing collected, runs on your machine.

[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://github.com/p1xelapp/solana-nft-mcp/blob/main/tsconfig.json)
[![MCP](https://img.shields.io/badge/MCP-official%20SDK-8b5cf6)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e)](https://github.com/p1xelapp/solana-nft-mcp/blob/main/LICENSE)
[![Sign-up](https://img.shields.io/badge/sign--up-none-f59e0b)](#what-it-reads)

</div>

---

## Why

Ask an assistant about a Solana card today and it answers from memory. It will say a card
"never traded", because the mainstream NFT APIs return an empty history for Metaplex Core
assets while the transfers sit on chain the whole time. It will compare two floors quoted in
two currencies as if they were one.

solana-nft-mcp hands the same assistant live, labelled data instead: the chain for supply,
ownership, provenance and custody rules, Magic Eden without a key, and OpenSea through a free
key the server issues itself. Each number comes back with its marketplace, its currency, its
read time, and what the source could not see.

<img src="assets/architecture.svg" alt="Your AI app talks to solana-nft-mcp over stdio; the server reads the Solana chain, the asset index, Magic Eden and OpenSea" width="100%" />

The server runs on your machine and your AI app starts it. There is no hosted service and no
account between you and the data. The picture is generated from the running server, so the
counts cannot drift from the code: `npm test` fails if they do.

## Install

Node 22 or newer. Two ways to run it.

**From npm, no clone.** Wherever a client asks for a command, give it `npx` with the arguments
`-y solana-nft-mcp`. This starts the published version. To run this checkout, use the source setup below.

```bash
claude mcp add solana-nft -- npx -y solana-nft-mcp
```

**From source.** Build once, then point the client at `dist/index.js`:

```bash
git clone https://github.com/p1xelapp/solana-nft-mcp.git
cd solana-nft-mcp && npm install && npm run build
```

Use an absolute path to the built file in each example. On Windows, a path
such as `C:/projects/solana-nft-mcp/dist/index.js` works in JSON. If the app
cannot find Node, use the full path to the Node executable for `command`.

**Claude Desktop.** Add this entry in Settings > Developer > Edit Config and
restart Desktop. You can also install the release's `.mcpb` from extension settings.

```json
{"mcpServers":{"solana-nft":{"command":"node","args":["/absolute/path/to/dist/index.js"]}}}
```

**Claude Code**

```sh
claude mcp add --transport stdio solana-nft -- node "/absolute/path/to/dist/index.js"
```

**Cursor.** Add to `.cursor/mcp.json`.

```json
{"mcpServers":{"solana-nft":{"command":"node","args":["/absolute/path/to/dist/index.js"]}}}
```

**VS Code with Copilot.** In the Copilot harness, add to the workspace root's `.mcp.json`.

```json
{"mcpServers":{"solana-nft":{"type":"stdio","command":"node","args":["/absolute/path/to/dist/index.js"],"tools":["*"]}}}
```

**Windsurf (now Devin Desktop).** For Devin Local, add to `.devin/mcp_config.local.json`.

```json
{"mcpServers":{"solana-nft":{"command":"node","args":["/absolute/path/to/dist/index.js"]}}}
```

**Gemini CLI.** Add to `~/.gemini/settings.json`.

```json
{"mcpServers":{"solana-nft":{"command":"node","args":["/absolute/path/to/dist/index.js"]}}}
```

**Codex CLI.** Add to `~/.codex/config.toml`.

```toml
[mcp_servers.solana-nft]
command = "node"
args = ["/absolute/path/to/dist/index.js"]
```

**Zed.** Add to Zed's settings JSON.

```json
{"context_servers":{"solana-nft":{"command":"node","args":["/absolute/path/to/dist/index.js"],"env":{}}}}
```

**Cline.** Open MCP Servers, choose Configure, and add this entry in the MCP settings file.

```json
{"mcpServers":{"solana-nft":{"command":"node","args":["/absolute/path/to/dist/index.js"]}}}
```

**Goose.** Add under `extensions` in `config.yaml`.

```yaml
extensions:
  solana-nft:
    name: solana-nft
    enabled: true
    type: stdio
    cmd: node
    args: ["/absolute/path/to/dist/index.js"]
```

**ChatGPT developer mode.** ChatGPT accepts an HTTPS MCP URL or a Secure MCP Tunnel.
For this stdio package, the tunnel client runs Node on your computer. Use an
existing tunnel ID, workspace access and a Platform runtime credential supplied
to the tunnel client. Choose Tunnel when adding the server in ChatGPT. [Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)

```sh
tunnel-client init --sample sample_mcp_stdio_local --profile solana-nft --tunnel-id YOUR_TUNNEL_ID --mcp-command "node /absolute/path/to/dist/index.js"
tunnel-client run --profile solana-nft
```

**Claude Messages API.** Its MCP connector calls tools on a publicly reachable Streamable HTTP or SSE server. Local SDK clients can call this package over stdio. The API's programmatic tool calling feature excludes connector-provided tools. [Connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) and [programmatic calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)

The stdio server negotiates 2025-11-25 and 2025-06-18. Clients configured to require
2026-07-28 need the newer protocol. For scripts, read `isError` before consuming
`structuredContent`. Successful replies also contain the same data as JSON text.

**Did it work?** Your app lists the tools near the message box (Claude Code: `/mcp`). You should
see 21, starting with `identify`. If none: the path must be absolute and end in `dist/index.js`,
`npm run build` must have run, and the app must be fully quit and reopened.

**OpenSea** is on without any setup. The first question that needs it makes the server ask
OpenSea for a free agent key, stored at `~/.solana-nft-mcp/opensea-key.json` and renewed before it
expires. The key is never logged or printed into an answer. A collection's OpenSea slug is found
from its on-chain address, or by name and then proved against that address; pass `openseaSlug`
to override. Options, set in the config's `env` block (clients launch the server with a clean
environment):

- `OPENSEA_API_KEY` - your own key, overrides the self-issued one.
- `SOLANA_NFT_MCP_NO_AUTO_KEYS=1` - never request a key; OpenSea is off unless you set one.
- `SOLANA_RPC_URL`, `DAS_RPC_URL` - a private endpoint, neither required. A key in the URL is
  registered and redacted from every answer (details in [docs/FAQ.md](https://github.com/p1xelapp/solana-nft-mcp/blob/main/docs/FAQ.md)).
- `SOLANA_NFT_MCP_NO_UPDATE_CHECK=1` - skip the one startup request to npm for a newer version.

In the Claude Desktop extension the same options are in the extension's settings, so there is
no config file to edit. What the server sends, to whom, and how it stores its key are listed
in [PRIVACY.md](https://github.com/p1xelapp/solana-nft-mcp/blob/main/PRIVACY.md).

## Ask it anything

Nobody types a tool name. These are asked in plain words and the assistant picks the calls.

- Who has owned this card since it was minted, with dates and the marketplaces involved?
- Is it true this card has never traded?
- Can the project still freeze, move or burn what is in my wallet?
- What is in wallet 7HHs3..., and does that wallet flip or hold?
- What is the cheapest Legendary listing in that DC collection right now?
- Any Superman or Batman DC comic #1 or #100 for sale, and are any close to floor?
- What did Shohei Ohtani cards sell for this week, and how many changed hands?
- Are the Magic Eden and OpenSea floors for this collection even comparable?
- What would it take to build a sales bot on this, and where would it fail quietly?

A collection name, a player name, a card number or a trait is enough to start. Names resolve
against a bundled snapshot of the Magic Eden directory, against OpenSea's Solana index, and
against the marketplace itself, and a fuzzy match is offered as a candidate with the mismatch
stated, never presented as the answer. Long answers are sized to arrive whole: a client that
caps a tool result gets fewer per-row details before it gets fewer rows, and the answer says
what it left out.

## What it reads

| Source | Answers | Key |
|---|---|---|
| Solana RPC (three public endpoints, rotated) | supply, current owner from decoded Core account bytes, transfer history, wallet age | none |
| Asset index (DAS) on the public RPC | a second, independent opinion on ownership and wallet contents | none |
| Magic Eden v2 | floors, listings, sales, activity, top traders, trending | none |
| OpenSea v2 | second-marketplace floors, sales, supply, royalty, wallet transfers | self-issued |

No account, no sign-in, no telemetry, no log of your questions, and no signing code anywhere in
the repository; every tool declares `readOnlyHint`. What leaves the machine: the public address,
symbol or name you asked about, sent to the source that can answer it; one startup request to
npm for the latest version number; one request to OpenSea for a free key, the first time a
question needs it. When saving a key, the server writes a temporary file and
renames it to `opensea-key.json`. An interrupted save can leave that temporary
file behind. To remove the stored credentials, delete `~/.solana-nft-mcp/`.

Key files use mode 600 on macOS and Linux. Windows uses the home folder's access
permissions; mode 600 does not set a Windows ACL. Keep that folder private to your
account. A linked key file or key directory is not used. If saving fails, the key
stays in memory and `get_source_status` reports that it was not saved.

## Tools

21 tools. Names are frozen: agents reference them in prompts, and a rename breaks integrations
without raising an error.

| Tool | Back |
|---|---|
| `identify` | what an address or name is, where it trades, which tool to call next |
| `verify_claim` | confirmed, contradicted or unverifiable, with the numbers seen and how to re-check; for a posted sale, the venue, buyer, seller and amounts read from the transaction itself |
| `get_asset_trust` | Core plugins decoded from bytes: delegates, frozen state, oracle checks that refuse transfers or burns right now, enforced vs advisory royalties, mutable metadata, editions |
| `get_integration_recipe` | endpoints, pacing, running cost, skeleton and the silent failure modes for a given build |
| `search_collections` | name lookup across the Magic Eden directory and the OpenSea Solana index, saying which layers were read |
| `get_collection_stats` | chain supply, floors per marketplace, and a reconciliation that refuses to rank SOL against USDC |
| `get_collection_holders` | census of a Core collection from the chain's asset index, each holder with a role (issuer, marketplace escrow, wallet), capped and saying so |
| `get_floor_prices` | current floor and listed count for up to 10 collections, Magic Eden only |
| `get_recent_sales` | latest completed fills with buyer, seller, price in the currency paid, mint and signature; with `chainScan`, the sales the feeds miss, read from the chain |
| `get_asset` | three readers for one item: the marketplace, a byte-level decode, and the chain's asset index, with owner agreement reported |
| `get_asset_provenance` | bounded ownership history of a Core asset, dated, marketplaces named, every unread hole marked in place. `historyComplete` says every transaction was read; `mintObserved` says the mint itself was decoded. They are different claims |
| `get_wallet_holdings` | holdings from two independent readers, with the gap between them named |
| `get_wallet_profile` | holdings by collection, share of wallet and of supply, listed and compressed counts, floor ceiling with assumptions, wallet age |
| `get_wallet_activity` | buys and sells, net flow, marketplace split, every flip with hold time and P&L, a behaviour label with its reason |
| `get_collection_sales` | sales over a window: count, volume, median, buyers, sellers, per-day series, per-name breakdown, how far back the feed was read |
| `find_in_group` | one edition number hunted across a whole family of collections, each match against its own floor |
| `find_listings` | cheapest-first listings, trait filters, a name filter that says what it matched, a lowest-serials mode, each ask against its trait floor on both marketplaces |
| `get_top_traders` | the largest wallets in a collection by Magic Eden volume |
| `get_trending` | Magic Eden's trending list, with an explicit note when the marketplace publishes nothing |
| `explain_mechanics` | escrow, freezing, delegates, royalties, wash trades and migrations, per standard and marketplace, each entry citing its source |
| `get_source_status` | every source pinged live: tier, fallback, what it cannot see, credential state |

Three prompts: `getting_started`, `collection_report`, `wallet_report`. No MCP resources, on
purpose: everything they would carry is reachable by a tool the assistant calls itself.

## Trust and limits

Candy announced its new site and wallet for November 18. Its
[storefront terms](https://candy.io/terms), read November 19, place secondary
sales on third-party marketplaces. On 2026-11-19 all 401 registered collections
carried burn-only oracle checks; the oracle still refused holder burns, while
transfers no longer consulted it. Use `get_asset_trust` on the card for the live
answer. A wallet migration is a transfer, not proof of a sale. Wallet indexes can
retain the old owner; `get_asset` checks current Core ownership against account bytes.

- Buying, selling, listing and signing are absent. No code exists for them.
- Provenance and trust decoding cover Metaplex Core only. Legacy SPL and compressed NFTs are
  reported as named gaps, never as empty lists. Holdings and activity cover both.
- Marketplace feeds: Magic Eden and OpenSea only. Tensor gives API access on request (its API
  page, read 2026-11-14), so its API is not called and its listings, bids and floor stay unread.
  Its sales of Metaplex Core items, and OpenSea's own Solana sales that Magic Eden's feed misses,
  are decoded from the chain instead: one transaction at a time by `verify_claim` with
  `claim: "sale"`, and as a bounded scan by `get_recent_sales` with `chainScan: true`, each
  reported as its own venue row. Rarible's Solana coverage is unconfirmed. Tensor's API and
  Rarible are catalogued with the condition that would add them.
- Every money figure names its currency and the API it came from, on the summary and on every
  priced row, and counts keep their coverage flags beside them (`truncated`, `stale`,
  `historyComplete`). A program should refuse to act on a row whose flag says the read was partial.
- For scripted calls, `identify` returns `lookup` with a tool name and arguments when
  the caller supplied the exact identifier. Check for `null` before using it.
  Names, summaries and candidate lists are display text.
- Two error surfaces. Input that fails a tool's schema is refused before the handler runs:
  `isError: true`, no `structuredContent`. Every failure inside a handler carries
  `structuredContent.error`. For example, `offline` means the server did not contact
  the source, `ambiguous` means the caller must choose a match, and
  `upstream-rate-limit` means the source asked callers to wait. Scripts should
  handle unknown categories and show the explanation that accompanies the error.
- No valuations and no currency conversion. Solana only.

Full detail: [docs/TRUST-AND-LIMITS.md](https://github.com/p1xelapp/solana-nft-mcp/blob/main/docs/TRUST-AND-LIMITS.md).

## Security

Minting is permissionless, so a collection name is attacker-controlled text. Every name and every
field from a chain or a marketplace is checked against the shape it claims to have before a model
sees it, and every credential this process has sent is redacted from every answer. Covered by the
offline suite. Reporting: [SECURITY.md](https://github.com/p1xelapp/solana-nft-mcp/blob/main/SECURITY.md).

## Development

```bash
npm test           # offline: every tool, prompt, validation, wallet and market logic,
                   # the OpenSea contract, the prompt-injection defence. No network.
npm run test:live  # live: floors, a real provenance trace, source status, name lookup
npm run snapshot   # refresh the bundled Magic Eden collection directory
npm run inspect    # open the MCP Inspector against a local build
```

CI runs a full-history secrets scan on every push to every branch; the offline suite, lint, the
tarball check and `npm audit` on `main`, pull requests and release tags; and the live check weekly.

## Docs

- [Under the hood: why it exists, how it works, what was tested](https://github.com/p1xelapp/solana-nft-mcp/blob/main/docs/DEEP-DIVE.md)
- [Every data source, tiered](https://github.com/p1xelapp/solana-nft-mcp/blob/main/docs/SOURCES.md)
- [Questions people ask, and which ones it can answer](https://github.com/p1xelapp/solana-nft-mcp/blob/main/docs/QUESTIONS.md)
- [Fifteen ways people use it](https://github.com/p1xelapp/solana-nft-mcp/blob/main/docs/HOW-PEOPLE-USE-IT.md) and [things people build with it](https://github.com/p1xelapp/solana-nft-mcp/blob/main/docs/BUILD-IDEAS.md)
- [What can change under this server](https://github.com/p1xelapp/solana-nft-mcp/blob/main/docs/MAINTENANCE.md), [FAQ](https://github.com/p1xelapp/solana-nft-mcp/blob/main/docs/FAQ.md), [Contributing](https://github.com/p1xelapp/solana-nft-mcp/blob/main/CONTRIBUTING.md)

## About

Built and maintained by P1xel ([p1xel.app](https://p1xel.app),
[@P1xelCollector](https://x.com/P1xelCollector)), a long-time Solana collector. The story of why it
exists is in [docs/DEEP-DIVE.md](https://github.com/p1xelapp/solana-nft-mcp/blob/main/docs/DEEP-DIVE.md).

### Running on the same decoding

<a href="https://candyscan.p1xel.app"><img src="assets/using/candyscan.png" width="86" alt="CandyScan" /></a>

**[CandyScan](https://candyscan.p1xel.app)** tracks the Candy Digital collections on Solana:
supply, holders, migrations and sales, kept current. It is where the Core decoding was written
first, and this repository is the keyless half of that pipeline. Each project shaped the other.

Shipped something on top of solana-nft-mcp? Open an issue and it goes here.

**Independent project, not affiliated with the Solana Foundation.** SOLANA and SOL are trademarks
of the Solana Foundation. They appear in this project's name and documentation for one reason
only: to say which chain the server reads. Nothing here is endorsed, sponsored or reviewed by the
Solana Foundation, and no affiliation is claimed or implied.

## License

MIT. See [LICENSE](https://github.com/p1xelapp/solana-nft-mcp/blob/main/LICENSE).

TDQS

A4.2/5.0

Scored across 21 tools

Disambiguation4/5

The descriptions go to unusual lengths to separate tools, explicitly stating when to use one vs another (e.g. get_floor_prices vs get_collection_stats, get_top_traders vs get_collection_sales vs get_collection_holders, get_wallet_holdings/profile/activity). Still, a few pairs genuinely overlap: get_recent_sales vs get_collection_sales both return collection sales, and the three wallet tools share a subject, so an agent could misselect without rereading the fine print.

Naming Consistency4/5

Names are uniformly lowercase snake_case and heavily dominated by a verb_noun pattern (get_collection_stats, get_wallet_activity, find_listings). Minor deviations exist: several verbs are synonyms for retrieval (get vs search_collections vs find_in_group), and identify/verify_claim/explain_mechanics drop the noun, but the set remains predictable.

Tool Count4/5

At 21 tools the surface is on the heavy side, but the domain genuinely spans collections, wallets, assets, sales, listings, provenance, trust and reference content, and each tool maps to a distinct query type. Nothing looks like filler, though a couple of retrieval tools could conceivably be merged.

Completeness5/5

For a deliberately read-only market/intelligence server the coverage is thorough: identification, discovery, floors/stats, listings, sales, holders, per-wallet and per-asset views, on-chain provenance and trust decoding, plus meta-tools (source status, mechanics, integration recipes, claim verification). No obvious lifecycle gap given the stated read-only purpose.

Maintenance

ActivityActive
ResponsivenessNo recent community issues