NEAR 协议全功能 MCP 服务器

本项目实现了一个模型上下文协议 (MCP) 服务器，用于与 NEAR 协议区块链进行交互。它允许通过 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 和 deposit。
• 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，它将使用从助记词派生的隐式账户。
• 工具权限： 此服务器授予连接的 LLM 客户端强大的功能。请注意您将其连接到哪些客户端，尤其是 delete_account、add_full_access_key 和 deploy_contract 等工具。
• 输入清理： 虽然 Zod 提供了基本的类型验证，但请确保在敏感操作（如合约调用或文件路径（如果扩展））中使用的任何用户/LLM 提供的输入都经过适当的清理。
• 速率限制： 对于生产服务器，请考虑添加速率限制以防止滥用。

🧪 开发

# 构建 TypeScript 代码
npm run build

# 检查 TypeScript 错误
npm run check-index

# 在开发模式下运行（构建 + 启动）
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