NEAR Protocol Full-Featured MCP Server

NEAR Protocol 全功能 MCP 服务

本项目实现了一个用于与 NEAR Protocol 区块链交互的模型上下文协议（MCP）服务。通过 MCP 客户端（如 Claude Desktop）连接的大语言模型（LLM）可以使用它查询区块链数据，并通过预先配置的 NEAR 账户执行交易。

⚠️ 安全警告：此服务使用存储在环境变量（MNEMONIC）中的助记词种子短语来派生用于签署交易的私钥。这种方法不适用于生产环境。请仅将此服务用于本地开发和测试，并使用不持有重要资产的账户。生产环境中，请采用更安全的密钥管理方案（例如 KMS、HSM 或专用密钥管理器）。

✨ 功能

此服务通过 MCP 工具提供以下功能：

• get_account_balance：获取指定账户（或未指定时获取服务账户）的总余额、质押余额、状态质押余额和可用余额。
• view_account_state：查看指定合约账户（或未指定时查看服务账户）中存储的原始键值状态。支持按可选的 Base64 编码键前缀进行筛选。
• get_account_details：获取指定 NEAR 账户（或未指定时获取服务账户）的详细信息，包括余额和存储用量。
• create_sub_account：在服务账户下创建新子账户。需要指定后缀、公钥和初始余额。
• delete_account：删除服务账户，并将剩余余额转给受益人。此操作不可逆！
• send_tokens：将 NEAR 代币从服务账户转至另一个账户。
• call_function：在指定的智能合约（或未指定时使用服务账户）上执行更改方法（函数调用），并可按需附加 Gas 和存款。
• batch_actions：在一笔针对指定接收方的交易中原子性地执行多个操作（未指定时使用服务账户）。
• deploy_contract：将 WASM 智能合约部署到服务配置的账户。需要提供 Base64 编码的 WASM 字节码。
• view_function：调用指定合约（或未指定时使用服务账户）上的只读函数。不会更改状态，也不会消耗大量 Gas。
• get_access_keys：列出与服务配置账户关联的所有访问密钥（公钥、权限、nonce）。
• add_full_access_key：向服务账户添加具有完全访问权限的新密钥。
• add_function_call_key：向服务账户添加具有受限函数调用权限（指定合约、方法和额度）的新密钥。
• delete_access_key：从服务账户中删除现有访问密钥。
• verify_signature：验证消息签名对于给定公钥是否有效。

🚀 前置条件

• **Node.js：**版本 16 或更高。（下载）
• npm（通常随 Node.js 一起安装）
• NEAR 账户（可选）：可以使用现有的 NEAR 账户（例如 testnet 或 mainnet 上的账户）及其12 或 24 个单词的助记词种子短语。如果没有账户，服务将使用根据种子短语派生的隐式账户。
• **NEAR 网络：**了解要连接的 networkId（testnet、mainnet）。
• **（可选）MCP 客户端：**可连接 MCP 服务的应用程序，例如 Claude for Desktop。

🛠️ 安装与设置

npm install near-mcp-server

1. 配置环境变量： 在项目根目录中创建一个 .env 文件。**重要提示：**将 .env 添加到 .gitignore 文件中，以免意外提交助记词！

   # .env
   # 替换为实际的 12 或 24 个单词的助记词（不要加引号）
   MNEMONIC="word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12"
   
   # 设置为 'testnet' 或 'mainnet'
   NEAR_NETWORK_ID="testnet"
   
   # 可选：如有需要，指定其他 RPC 节点 URL
   # NEAR_NODE_URL="https://rpc.testnet.near.org"
   

2. **构建服务：**将 TypeScript 代码编译为 JavaScript。

   npm run build
   

   这会创建一个 build 目录，其中包含编译后的 index.js 文件，并使其可执行。

🏃 运行服务

你可以通过以下几种方式运行服务：

• 使用 npm start：

  npm start
  

• 直接使用 Node：

  node build/index.js
  

• 使用二进制名称（如果已链接或全局安装）：

  near-mcp-server-full
  

初始化成功后，服务会将连接详情记录到 stderr： Connected to NEAR <networkId> as <accountId> NEAR MCP Server running on stdio...

使用客户端连接服务期间，请保持终端运行。服务的日志和错误会显示在此终端中（stderr）。

🔑 默认账户行为

此服务实现按以下方式处理账户 ID：

1. 在工具函数中明确提供账户 ID 时（例如，get_account_balance({ accountId: "example.near" })），将使用指定的账户。

2. 未提供账户 ID 时，服务将使用自己的账户（由 MNEMONIC 派生的账户）。

3. 如果服务没有已建立的账户 ID（例如，使用尚未在链上创建的账户的助记词时），则会回退到使用由助记词的公钥派生的隐式账户 ID。

此行为让工具能够无缝地处理明确指定的账户和服务自身的账户，从而提供更好的用户体验。

🔌 连接到客户端（示例：Claude Desktop）

1. **查找 Claude 配置：**找到 Claude Desktop 配置文件：

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows： %APPDATA%\Claude\claude_desktop_config.json （如果文件不存在，请创建该文件。）

2. **编辑配置：**在 mcpServers 下添加此服务的条目。请使用项目目录中已编译的 build/index.js 文件的绝对路径。

   {
     "mcpServers": {
       "near-protocol-server": {
         "command": "node",
         "args": [
           "/path/to/your/project/near-mcp-server/build/index.js"
         ]
         "env": {
           "MNEMONIC": "...",
           "NEAR_NETWORK_ID": "testnet"
         }
       }
     }
   }
   

3. **重启 Claude：**保存配置文件，并完全退出后重新启动 Claude Desktop 应用程序。

4. **验证连接：**在聊天输入区域查找锤子图标。点击后应会列出此服务中定义的 NEAR 工具。

💬 使用示例（搭配 Claude Desktop）

连接后，你可以让 Claude 使用 NEAR 工具：

• What's the balance of my account?（使用服务的账户）
• What's the balance of vitalik.near?（指定账户）
• Get the account details for vitalik.near
• View the state for contract guest-book.testnet
• Send 0.1 NEAR from my account to friend.testnet
• Call the 'add_message' function on 'guest-book.testnet' with arguments {"text": "Hello from MCP!"}
• Call the 'set_greeting' function on my contract with arguments {"message": "Hello"}
• Deploy this contract (provide base64 WASM) to my account
• Create a subaccount 'mysub' under my account with public key 'ed25519:...' and fund it with 0.5 NEAR
• Show me all access keys for my account
• Add a full access key 'ed25519:...' to my account
• Delete the access key 'ed25519:...' from my account
• Delete my account and send the funds to 'beneficiary.testnet'（请格外谨慎！）
• Verify the message "test message" against signature "base64..." using public key "ed25519:..."
• Execute these actions in a batch for my account: transfer 0.1 NEAR to bob.testnet, then call method 'increase' on counter.testnet

Claude 会识别合适的工具，并在执行任何会修改状态或花费资金的交易前征求你的确认。

🔒 安全注意事项

• 私钥（助记词）： 将助记词存储在 .env 中，除了本地测试之外都不安全。不要对持有真实资产的账户使用此方法。生产环境中可考虑使用硬件钱包、安全飞地解决方案或 KMS。确保 .env 文件已列入 .gitignore。
• 隐式账户： 如果请求中未明确指定账户 ID，服务将使用自身的账户 ID。如果服务没有现有账户 ID，则会使用根据助记词派生的隐式账户。
• 工具权限： 此服务会向连接的大模型客户端授予强大的能力。请谨慎选择要连接的客户端，尤其是使用 delete_account、add_full_access_key 和 deploy_contract 等工具时。
• 输入清理： 虽然 Zod 提供基本的类型验证，但对于用于敏感操作的用户或大模型输入（例如合约调用，或扩展后的文件路径），请确保经过适当清理。
• 速率限制： 对于生产服务，可考虑添加速率限制以防止滥用。

🧪 开发

# Build the TypeScript code
npm run build

# Check TypeScript errors
npm run check-index

# Run in development mode (build + start)
npm run dev

🔧 故障排除

• 服务无法启动： 查看运行 npm start 的终端中是否有错误。确保 .env 中的所有环境变量均已正确设置。确认已安装 Node.js v16+。
• 客户端中未显示（Claude）：
  • 再次检查 claude_desktop_config.json 语法。
  • 确认 build/index.js 的绝对路径正确。
  • 完全重启 Claude Desktop。
  • 查看 Claude 的 MCP 日志。
• 工具错误： 查看服务的终端输出（stderr），了解 near-api-js 或 NEAR 网络返回的具体错误消息。常见问题包括余额不足、账户 ID 不正确或网络问题。

🤝 贡献

欢迎贡献！如果你有建议或改进，请提交 issue 或 pull request。

📜 许可证

MIT