快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

详细介绍

🚀 NFT IPFS to Filecoin Migration MCP Server

一句话说明: 通过 Claude Desktop 对话完成 NFT 元数据从 IPFS 到 Filecoin 的迁移，并在 ERC-8004 链上记录验证。

最新测试: ✅ 2025-11-12 完整流程验证通过 (Agent ID: 145, Response: 100)

📋 项目概述

这是一个 Model Context Protocol (MCP) 服务器，允许你通过自然语言对话完成 NFT 元数据迁移：

NFT (以太坊主网) → IPFS 元数据 → Filecoin 永久存储 → Sepolia 链上验证

核心功能

✅ NFT 扫描: 获取以太坊主网 NFT 元数据
✅ Filecoin 上传: 将元数据上传到 Filecoin 网络
✅ ERC-8004 验证: AI Agent 注册和链上验证
✅ 对话式操作: 通过 Claude Desktop 简单对话完成所有步骤

🎯 快速开始（5 分钟）

1. 安装依赖

npm install
npm run build

2. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，填入你的私钥和 RPC URL

重要: 需要两个不同的钱包地址：

PRIVATE_KEY: Agent 拥有者钱包
VALIDATOR_PRIVATE_KEY: 验证者钱包（必须不同）

3. 配置 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nft-migration": {
      "command": "node",
      "args": ["/绝对路径/mcp-nft-migration/build/index.js"]
    }
  }
}

4. 重启 Claude Desktop

重启后看到 🔨 图标即表示 MCP 服务器已加载。

💬 使用方式

详细对话步骤请查看 → CHAT_GUIDE.md

简单示例

你: 验证环境配置
Claude: ✅ 环境就绪，FIL 余额 104.99

你: 注册一个 NFT Migration Agent
Claude: ✅ Agent ID: 145

你: 上传 Azuki #1 到 Filecoin
Claude: ✅ PieceCID: bafkz...

你: 创建验证请求并提交
Claude: ✅ 验证通过！Response: 100

🛠️ MCP 工具列表

环境设置工具

工具	功能
`verify_setup`	验证环境配置（私钥、SDK、余额、授权）
`setup_approvals`	自动设置 Filecoin 存储授权（存入 USDFC）
`check_balances`	检查钱包余额（FIL、USDFC、Payments）

NFT 扫描工具

工具	功能
`nft_scan`	扫描以太坊 NFT 合约，获取 NFT 列表
`get_nft_metadata`	获取单个 NFT 的元数据（IPFS/HTTP）

Filecoin 上传工具

工具	功能
`upload_to_filecoin`	上传 NFT 元数据到 Filecoin，返回 PieceCID
`test_upload`	使用测试数据测试 Filecoin 上传功能
`batch_upload_azuki`	批量上传 Azuki NFT 到 Filecoin

ERC-8004 验证工具

工具	功能
`register_agent`	在 ERC-8004 合约上注册 AI Agent
`get_agent_info`	查询 Agent 信息（ID、Owner、状态）
`create_validation_request`	创建 ERC-8004 验证请求，记录迁移任务
`submit_validation`	提交验证结果和证明到链上
`get_validation_status`	查询验证请求的状态和结果
`update_agent_metadata`	更新 Agent metadata，记录 Filecoin URI

📁 项目结构

mcp-nft-migration/
├── src/                    # TypeScript MCP 服务器源码
│   ├── index.ts           # MCP 服务器入口
│   ├── index-daemon.ts    # 守护进程模式
│   ├── tools/             # MCP 工具实现
│   │   ├── setup.ts       # 环境验证和授权设置
│   │   ├── upload.ts      # Filecoin 上传
│   │   ├── nft.ts         # NFT 扫描和元数据获取
│   │   └── validation.ts  # ERC-8004 验证
│   ├── resources/         # MCP 资源
│   └── prompts/           # MCP 提示模板
│
├── lib/                   # 核心业务逻辑（JavaScript）
│   ├── core/              # 核心模块
│   │   ├── filecoin-uploader.js   # Filecoin 上传器
│   │   ├── nft-scanner.js         # NFT 扫描器
│   │   └── erc8004-client.js      # ERC-8004 客户端
│   ├── scripts/           # 辅助脚本
│   │   ├── setup-via-sdk.js       # 授权设置
│   │   ├── pre-upload-check.js    # 上传前检查
│   │   └── check-balances.js      # 余额检查
│   └── utils/             # 工具函数
│
├── examples/              # 示例代码
│   ├── demo.js           # 完整演示
│   └── scan-azuki.js     # Azuki 扫描示例
│
├── build/                # 编译输出
├── temp/                 # 临时文件
├── .env.example          # 环境变量模板
├── package.json          # 依赖配置
└── README.md             # 本文档

🚀 快速开始

1. 克隆项目

git clone 
cd mcp-nft-migration

2. 安装依赖

npm install

这将自动安装所有依赖，包括：

MCP SDK
Synapse SDK (v0.35.3)
Ethers.js
其他工具库

3. 配置环境

复制环境变量模板并填写：

cp .env.example .env

编辑 .env 文件：

# 钱包私钥（测试网）
PRIVATE_KEY=0x...

# 钱包地址
WALLET_ADDRESS=0x...

# 以太坊 RPC（读取 NFT）
ETHEREUM_MAINNET_RPC_URL=https://eth-mainnet.public.blastapi.io
ETHEREUM_NETWORK_RPC_URL=https://eth-sepolia.public.blastapi.io

# Filecoin RPC（存储）
FILECOIN_NETWORK_RPC_URL=https://api.calibration.node.glif.io/rpc/v1

# ERC-8004 合约（可选）
ERC8004_CONTRACT_ADDRESS=0x...

4. 构建项目

npm run build

5. 配置 Claude Code Desktop

编辑 ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nft-migration": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-nft-migration/build/index.js"],
      "env": {
        "PRIVATE_KEY": "0x...",
        "WALLET_ADDRESS": "0x...",
        "ETHEREUM_NETWORK_RPC_URL": "https://eth-sepolia.public.blastapi.io",
        "FILECOIN_NETWORK_RPC_URL": "https://api.calibration.node.glif.io/rpc/v1",
        "ETHEREUM_MAINNET_RPC_URL": "https://eth-mainnet.public.blastapi.io"
      }
    }
  }
}

重要提示：

使用绝对路径
环境变量可以在这里直接配置（会覆盖 .env 文件）
设置文件权限：chmod 600 ~/.config/Claude/claude_desktop_config.json

6. 重启 Claude Code Desktop

完全退出并重新启动 Claude Code。

7. 验证安装

在 Claude Code 中输入：

请检查我的 Filecoin 环境配置。

Claude 将调用 verify_setup 工具，检查所有配置。

📖 使用示例

示例 1: 首次设置

我是第一次使用，请帮我设置 Filecoin 环境。

Claude 会：

验证环境配置
检查余额
设置授权（存入 USDFC 并授权 Warm Storage）
确认设置成功

示例 2: 扫描 NFT 合约

请扫描 Azuki 合约 0xed5af388653567af2f388e6224dc7c4b3241c544 的前 5 个 NFT。

Claude 会：

调用 nft_scan 工具
返回 NFT 列表
显示 Token IDs、Owners、元数据
列出发现的 IPFS CIDs

示例 3: 上传单个 NFT 到 Filecoin

请将 Azuki #0 上传到 Filecoin，合约地址是 0xed5af388653567af2f388e6224dc7c4b3241c544。

Claude 会：

获取 NFT 元数据
验证环境配置
上传到 Filecoin
返回 PieceCID 和验证链接

示例 4: 批量迁移

请批量上传 Azuki 合约的所有 NFT。

Claude 会：

扫描所有 NFT
逐个上传到 Filecoin
统计成功/失败数量
生成详细报告

示例 5: 故障排查

我遇到了 "Insufficient USDFC" 错误，怎么办？

Claude 会：

检查余额
建议从水龙头获取 USDFC
指导设置授权
提供详细解决方案

🛠️ 可用命令

开发命令

# 构建项目
npm run build

# 监听文件变化（开发模式）
npm run watch

# 运行 stdio 模式（手动测试）
npm run dev

# 运行守护进程模式
npm run daemon

实用脚本

# 运行完整演示
npm run demo

# 环境设置（存入 USDFC 并授权）
npm run setup

# 检查环境配置
npm run check

手动测试

# 验证环境
node lib/scripts/pre-upload-check.js

# 设置授权
node lib/scripts/setup-via-sdk.js

# 检查余额
node lib/scripts/check-balances.js

# 扫描 Azuki NFT
node examples/scan-azuki.js

🏗️ 技术架构

用户（自然语言）
    ↓
Claude Code Desktop
    ↓ MCP Protocol
MCP Server（TypeScript）
    ├── src/tools/         # 工具层（调用 lib/）
    ├── src/resources/     # 资源层
    └── src/prompts/       # 提示层
    ↓
Core Library（JavaScript）
    ├── lib/core/          # 核心业务逻辑
    │   ├── filecoin-uploader.js
    │   ├── nft-scanner.js
    │   └── erc8004-client.js
    └── lib/scripts/       # 辅助脚本
        ├── setup-via-sdk.js
        ├── pre-upload-check.js
        └── check-balances.js
    ↓
External Services
    ├── Filecoin Calibration (Synapse SDK)
    ├── Ethereum Sepolia (ERC-8004)
    └── Ethereum Mainnet (NFT 读取)

🔧 技术栈

核心依赖

MCP SDK: @modelcontextprotocol/sdk ^1.20.1
Synapse SDK: @filoz/synapse-sdk ^0.35.3
Ethers.js: ethers ^6.9.0
Axios: axios ^1.6.2
Zod: zod ^3.22.4
Express: express ^4.18.2

开发依赖

TypeScript: typescript ^5.3.0
Node Types: @types/node ^20.10.0
Express Types: @types/express ^4.17.21
Prettier: prettier ^3.1.0

运行环境

Node.js: >= 18.0.0
操作系统: macOS, Linux, Windows

🌐 网络配置

Ethereum Sepolia（ERC-8004 验证）

RPC: https://eth-sepolia.public.blastapi.io
用途: 部署和调用 ERC-8004 验证合约
Chain ID: 11155111

Filecoin Calibration（存储）

RPC: https://api.calibration.node.glif.io/rpc/v1
用途: 上传 NFT 元数据到 Filecoin
SDK: Synapse SDK v0.35.3
Chain ID: 314159

Ethereum Mainnet（只读）

RPC: https://eth-mainnet.public.blastapi.io
用途: 读取 NFT 合约（只读，不发送交易）
Chain ID: 1

💰 所需代币

1. Sepolia ETH

用途: ERC-8004 验证交易 gas
获取: https://sepoliafaucet.com/
所需数量: ~0.01 ETH

2. Calibration FIL

用途: Filecoin 交易 gas
获取: https://faucet.calibnet.chainsafe-fil.io/
所需数量: ~100 FIL（测试网）

3. USDFC

用途: Filecoin 存储费用
获取: https://pdp.vxb.ai/faucet
所需数量: ~35 USDFC（可设置）

⚠️ 注意事项

1. 私钥安全

配置文件中的私钥是明文存储
仅用于测试网
设置正确的文件权限：chmod 600 ~/.config/Claude/claude_desktop_config.json
永远不要在主网使用这些配置

2. Storage Provider 性能

Calibration 测试网的 SP 可能响应较慢
上传超时不一定是代码问题
建议在网络良好时测试
可能需要等待几分钟才能完成上传

3. 文件大小要求

Storage Provider 要求最小文件大小 1 MB
小于 1 MB 的元数据会自动填充
填充数据不影响原始元数据

4. 授权设置

必须先运行 setup_approvals 设置授权
否则会遇到错误码 33（Insufficient allowance）
授权会定期过期，需要重新设置

5. 余额要求

FIL 余额需充足（建议 > 100 FIL）
USDFC 钱包余额需 >= 存款金额
Payments 合约余额需 > 0

🐛 故障排查

错误码 33

症状: PaymentsService error: code 33

原因: Payments 合约余额不足或服务授权未设置

解决方案:

# 1. 检查余额
npm run check

# 2. 设置授权
npm run setup

SDK 初始化失败

症状: Failed to initialize Synapse SDK

原因: 私钥或 RPC URL 配置错误

解决方案:

检查 .env 文件配置
验证私钥格式（必须以 0x 开头）
测试 RPC URL 连通性

上传超时

症状: 上传过程卡住或超时

原因: Storage Provider 响应慢或网络问题

解决方案:

检查网络连接
稍后重试
使用较小的测试文件

NFT 扫描失败

症状: Failed to scan NFT contract

原因: RPC 限流或合约地址错误

解决方案:

验证合约地址格式
检查 RPC URL 配置
稍后重试

📚 相关文档

ERC8004_INTEGRATION.md - ERC-8004 集成指南
CLAUDE_CODE_SETUP.md - Claude Code 详细配置
.env.example - 环境变量配置模板
examples/ - 示例代码和用法

🧪 测试

单元测试

# 测试环境配置
node lib/scripts/pre-upload-check.js

# 测试小文件上传
# （在 Claude Code 中）
请测试 1.1 MB 的文件上传。

集成测试

# 运行完整演示
npm run demo

MCP 服务器测试

# 直接运行（stdio 模式）
node build/index.js

# 应该输出:
# NFT Migration MCP Server running on stdio

🤝 贡献

欢迎贡献代码、报告问题或提出建议！

开发流程

Fork 项目
创建特性分支：git checkout -b feature/amazing-feature
提交更改：git commit -m 'Add amazing feature'
推送分支：git push origin feature/amazing-feature
提交 Pull Request

代码规范

TypeScript 代码使用 ESLint
JavaScript 代码使用 Prettier
提交信息遵循 Conventional Commits

📄 许可证

MIT License

🎉 致谢

📞 支持

如有问题或需要帮助，请：

查看本 README 的故障排查部分
查看相关文档
提交 GitHub Issue

Happy Migrating! 🚀

目录标签

JavaScriptClaude金融数据NFT迁移本地部署Filecoin存储区块链验证对话式操作元数据管理

支持客户端

Claude DesktopClaude

接入字段

传输方式（transport，传输协议）

未说明

鉴权方式（authType，认证方式）

token

工具数量（toolCount，工具数）

14

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

未说明token部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

仍需确认：installCommand

来源信息

MCP World

mcpworld.com

/detail/748d1584088754b3572e80f89855eca9

通过对话式操作完成NFT元数据从IPFS到Filecoin的迁移，并在ERC-8004链上记录验证的服务。

继续浏览同类 MCP

更多金融服务 MCP（2,622）返回 MCP 目录

上一个 MCP

Fetch AI MCP

用于监控和分析Fetch.ai自主代理经济的生产级MCP服务器，提供实时代理交互、微交易和网络健康分析。

下一个 MCP

FI MCP

FI-MCP是一个自动从金融独立函数库生成MCP工具的服务，确保AI助手使用正确的金融计算功能，避免猜测或使用错误的计算。

Filecoin MCP Nft Migration

快速接入

详细介绍

🚀 NFT IPFS to Filecoin Migration MCP Server

📋 项目概述

核心功能

🎯 快速开始（5 分钟）

1. 安装依赖

2. 配置环境变量

3. 配置 Claude Desktop

4. 重启 Claude Desktop

💬 使用方式

简单示例

🛠️ MCP 工具列表

环境设置工具

NFT 扫描工具

Filecoin 上传工具

ERC-8004 验证工具

📁 项目结构

🚀 快速开始

1. 克隆项目

2. 安装依赖

3. 配置环境

4. 构建项目

5. 配置 Claude Code Desktop

6. 重启 Claude Code Desktop

7. 验证安装

📖 使用示例

示例 1: 首次设置

示例 2: 扫描 NFT 合约

示例 3: 上传单个 NFT 到 Filecoin

示例 4: 批量迁移

示例 5: 故障排查

🛠️ 可用命令

开发命令

实用脚本

手动测试

🏗️ 技术架构

🔧 技术栈

核心依赖

开发依赖

运行环境

🌐 网络配置

Ethereum Sepolia（ERC-8004 验证）

Filecoin Calibration（存储）

Ethereum Mainnet（只读）

💰 所需代币

1. Sepolia ETH

2. Calibration FIL

3. USDFC

⚠️ 注意事项

1. 私钥安全

2. Storage Provider 性能

3. 文件大小要求

4. 授权设置

5. 余额要求

🐛 故障排查

错误码 33

SDK 初始化失败

上传超时

NFT 扫描失败

📚 相关文档

🧪 测试

单元测试

集成测试

MCP 服务器测试

🤝 贡献

开发流程

代码规范

📄 许可证

🎉 致谢

📞 支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP