solana-nft-mcp

---

原因

如今，询问助手一张 Solana 卡的情况，它只会根据记忆作答。它会说这张卡 “从未交易过”，因为主流 NFT API 对 Metaplex Core 资产返回空历史记录，而这些资产的转移其实一直都记录在链上。它还会把以两种货币报价的两个地板价当成同一种货币进行比较。

solana-nft-mcp 为同一个助手提供实时、带标签的数据：从链上读取供应量、 所有权、来源和托管规则；无需密钥即可访问 Magic Eden；还可通过服务自行签发的免费 密钥访问 OpenSea。每个数字都会附带其市场、货币、读取时间，以及数据源无法获取的信息。

服务在你的机器上运行，由你的 AI 应用启动。你与数据之间没有托管服务或 账户。示意图根据运行中的服务生成，因此图中计数不会与代码不符：如果不符， npm test 就会失败。

安装

需要 Node 22 或更高版本。有两种运行方式。

通过 npm 安装，无需克隆。 客户端要求提供命令时，填写 npx，并添加参数 -y solana-nft-mcp。首次启动时会下载软件包；之后的启动会复用它。

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

从源代码安装。 构建一次，然后将客户端指向 dist/index.js：

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

Claude Code

claude mcp add solana-nft -- node /absolute/path/to/solana-nft-mcp/dist/index.js

Claude Desktop。 依次选择 Settings -> Developer -> Edit Config，添加下面的配置块，然后完全退出并重新打开应用。或者，从最新版本中下载 .mcpb bundle，将它拖到 Settings -> Extensions 上进行安装。

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

其他客户端。 已测试：Claude Desktop、Claude Code、Codex CLI 0.153.4 （codex exec -c 'mcp_servers.solana-nft.command="node"' -c 'mcp_servers.solana-nft.args=["/absolute/path/to/dist/index.js"]'）。 Cursor、Windsurf、Gemini CLI、Zed、Cline 和 VS Code 在各自的配置中使用相同的 command / args 配置；服务使用普通的 stdio，不含任何特定于客户端的代码，但尚未在这些客户端上测试。网页版 ChatGPT 和 Grok 无法运行本地进程。 该服务通过官方 TypeScript SDK v1 使用 MCP 协议修订版 2025-11-25。提供较新的 2026-07-28 修订版的客户端会收到 2025-11-25 版本，当前客户端都能接受；拒绝任何较旧版本的客户端目前无法使用此服务。

运行成功了吗？ 应用会在消息框附近列出工具（Claude Code：/mcp）。应该能看到 21 个工具，以 identify 开头。如果一个都没有：路径必须是绝对路径，并以 dist/index.js 结尾；必须运行过 npm run build；并且必须完全退出并重新打开应用。

OpenSea 无需设置即可使用。第一个需要 OpenSea 的问题会让服务向 OpenSea 申请免费的 Agent 密钥，并将密钥存储在 ~/.solana-nft-mcp/opensea-key.json 中，在过期前续期。密钥绝不会写入日志或输出到回答中。服务会根据链上地址查找藏品的 OpenSea slug，或者先按名称查找，再通过该地址验证；传入 openseaSlug 可覆盖此设置。选项在配置的 env 块中设置（客户端会在干净的环境中启动服务）：

• OPENSEA_API_KEY - 使用你自己的密钥，并覆盖自动签发的密钥。
• SOLANA_NFT_MCP_NO_AUTO_KEYS=1 - 永不申请密钥；除非你自行设置密钥，否则 OpenSea 将不可用。
• SOLANA_RPC_URL、DAS_RPC_URL - 私有端点，均非必需。URL 中的密钥会被登记，并从所有回答中脱敏（详情参见 docs/FAQ.md）。
• SOLANA_NFT_MCP_NO_UPDATE_CHECK=1 - 跳过启动时向 npm 查询是否有新版本的唯一一次请求。

想问什么都行

没人需要输入工具名称。用日常语言提问，助手会选择要调用的工具。

• 这张卡片自铸造以来有哪些持有者，分别持有了多久，涉及哪些交易市场？
• 这张卡片从未交易过，是真的吗？
• 项目方还能冻结、转移或销毁我钱包里的资产吗？
• 钱包 7HHs3... 里有什么？这个钱包会频繁倒手还是长期持有？
• 这个 DC 藏品中最便宜的传奇卡挂牌价是多少？
• 有 Superman 或 Batman 的 DC 漫画第 1 期或第 100 期在售吗？有没有接近地板价的？
• Shohei Ohtani 卡片本周的成交价是多少？有多少张易主？
• 这个藏品在 Magic Eden 和 OpenSea 上的地板价有可比性吗？
• 要在这个基础上构建一个销售机器人需要做些什么？它可能会在哪些地方悄无声息地失效？

提供藏品名称、球员姓名、卡片编号或特征即可开始搜索。名称会与打包的 Magic Eden 目录快照、OpenSea 的 Solana 索引以及交易市场本身进行匹配；如果找到的是模糊匹配，会将其作为候选项提供，并说明不匹配之处，绝不会直接当作答案。长答案会经过调整，确保能完整送达：如果客户端限制工具结果大小，系统会优先减少每行的详细信息，而不是减少行数，并说明省略了哪些内容。

它读取的内容

来源	可回答的问题	密钥
Solana RPC（三个公共端点，轮换使用）	供应量、从解码后的 Core 账户字节中获取的当前所有者、转移历史、钱包创建时间	无
公共 RPC 上的资产索引（DAS）	关于所有权和钱包内容的另一份独立意见	无
Magic Eden v2	地板价、挂单、销售、活动、顶级交易者、趋势	无
OpenSea v2	第二个市场的地板价、销售、供应量、版税、钱包转账	自行签发

无需账户，无需登录，不收集遥测数据，不记录你的问题，仓库中也没有任何签名代码；每个工具都声明了 readOnlyHint。离开本机的数据：你查询的公共地址、符号或名称，会发送给能够回答该问题的数据源；启动时向 npm 请求一次最新版本号；首次遇到需要密钥的问题时，向 OpenSea 请求一次免费密钥。只会写入一个文件，即上面的密钥文件，权限为 600。除此之外，不会有任何内容写入磁盘。要彻底移除所有内容：卸载或删除克隆目录，然后删除 ~/.solana-nft-mcp/。

工具

21 个工具。名称已固定：Agent 会在提示词中引用这些名称，重命名会破坏集成，且不会报错。

工具	用途
identify	识别某个地址或名称、其交易平台，以及下一步应调用哪个工具
verify_claim	判定已确认、已证伪或无法验证，并提供看到的数值及复查方法
get_asset_trust	解码字节中的 Core 插件：委托方、冻结状态、当前会拒绝转账或销毁的预言机检查、强制执行与建议性质的版税、可变元数据、版本
get_integration_recipe	针对特定构建提供端点、调用节奏、运行成本、框架，以及那些不会发出提示的故障模式
search_collections	在 Magic Eden 目录和 OpenSea Solana 索引中查找名称，并说明读取了哪些数据层
get_collection_stats	链上供应量、各市场的地板价，以及拒绝将 SOL 与 USDC 排名比较的对账结果
get_collection_holders	从链上资产索引统计 Core 集合的持有者，为每位持有者标注角色（发行方、市场托管账户、钱包），并注明结果已设上限
get_floor_prices	查询最多 10 个集合的当前地板价和在售数量，仅限 Magic Eden
get_recent_sales	最新完成的成交记录，包含买家、卖家、价格、铸造地址和签名
get_asset	用三个读取器查询单个项目：市场、字节级解码和链上资产索引，并报告所有者是否一致
get_asset_provenance	Core 资产有限范围内的所有权历史，附日期和市场名称，并在原处标出每个未读取的缺口。historyComplete 表示已读取每笔交易；mintObserved 表示已解码铸造本身。这是两种不同的声明
get_wallet_holdings	从两个独立读取器获取持仓，并明确指出两者之间的差异
get_wallet_profile	按集合列出持仓、占钱包和供应量的比例、在售数量与压缩资产数量、带假设条件的地板价上限，以及钱包年龄
get_wallet_activity	买入和卖出、净流量、市场分布、每次倒卖的持有时长和盈亏，以及附带理由的行为标签
get_collection_sales	指定时间段内的销售数据：数量、成交额、中位数、买家、卖家、逐日序列、按名称细分，以及数据源回溯读取的范围
find_in_group	在整个系列的集合中查找一个版本号，并将每个匹配项与其自身的地板价进行比较
find_listings	按价格从低到高排列的在售项目、特征筛选、注明匹配内容的名称筛选、最低编号模式，以及在两个市场上将每个要价与其特征地板价进行比较
get_top_traders	按 Magic Eden 成交额列出集合中规模最大的几个钱包
get_trending	Magic Eden 的趋势榜单；若市场未发布任何内容，会明确说明
explain_mechanics	说明托管、冻结、委托方、版税、刷量交易和迁移机制，按标准和市场分类，并为每条说明注明来源
get_source_status	实时检测的每个数据源：层级、回退方案、不可见内容、凭据状态

三个提示词：getting_started、collection_report、wallet_report。特意不提供 MCP 资源：这些资源本来会包含的所有内容，都可以通过助手自行调用的工具获取。

信任与限制

• 不支持购买、出售、上架和签名，也不存在相关代码。
• 来源信息和信任解码仅覆盖 Metaplex Core。Legacy SPL 和压缩 NFT 会作为明确缺口报告，不会显示为空列表。持有情况和活动则同时覆盖两者。
• 仅支持 Magic Eden 和 OpenSea。Tensor 不提供自助密钥；Rarible 对 Solana 的支持情况尚未确认。两者都已列入目录，并注明了添加它们所需的条件。
• 每个金额都会标明币种和来源 API，包括摘要以及每一行定价数据；计数旁也会附上覆盖标记（truncated、stale、historyComplete）。如果某一行的标记表明读取不完整，程序就应拒绝对其执行操作。
• 有两种错误形式。工具输入未通过架构校验时，会在处理函数运行前被拒绝：isError: true，且没有 structuredContent。处理函数内部的每种失败都会携带 structuredContent.error，并使用稳定的类别（not-found、wrong-kind、escrow、source-unsupported、bad-input、upstream-unavailable、upstream-rate-limit、error）。
• 不提供估值，也不进行币种转换。仅支持 Solana。

完整详情：docs/TRUST-AND-LIMITS.md。

安全

铸造无需许可，因此藏品名称是由攻击者控制的文本。在模型看到任何名称以及来自链或市场的任何字段之前，都会检查其是否符合所声称的格式；此流程发送的所有凭据也会从每个回答中删除。相关检查由离线测试套件覆盖。报告方式：SECURITY.md。

开发

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 会在每次推送到任何分支时执行完整历史记录的密钥扫描；在 main、拉取请求和发布标签上运行离线测试套件、lint、tarball 检查和 npm audit；并每周执行实时检查。

文档

• 幕后详情：存在的原因、工作方式及测试内容
• 所有数据来源及其分级
• 大家常问的问题，以及它能回答哪些问题
• 人们使用它的 15 种方式以及人们用它构建的项目
• 此服务之下可能发生的变化、常见问题、贡献指南

关于

由长期收集 Solana 藏品的 P1xel 构建并维护（p1xel.app、@P1xelCollector）。项目缘起见 docs/DEEP-DIVE.md。

基于相同解码运行

CandyScan 追踪 Solana 上 Candy Digital 藏品的供应量、持有者、迁移和销售情况，并保持数据最新。Core 解码最初就是在这里编写的，而本仓库则是该流程中无需密钥的部分。两个项目相互塑造、彼此影响。

如果你基于 solana-nft-mcp 构建了项目，欢迎提交 issue，项目就会展示在这里。

独立项目，与 Solana Foundation 无关联。 SOLANA 和 SOL 是 Solana Foundation 的商标。它们出现在本项目名称和文档中的唯一原因，是说明此服务读取的是哪条链。Solana Foundation 不认可、不赞助也未审查本项目；本项目未声称或暗示与其存在任何关联。

许可证

MIT。请参阅 LICENSE。