Near MCP Server

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：对指定的合约（或未指定的服务器帐户）调用仅查看函数。不会改变状态或消耗大量天然气。
• get_access_keys：列出与服务器配置的帐户关联的所有访问密钥（公钥、权限、随机数）。
• 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桌面版.

🛠️ 安装和设置

npm install near-mcp-server

1. 配置环境变量：

创建一个 .env 项目根目录中的文件。 重要提示： 添加 .env 到你的 .gitignore 文件，以避免意外提交您的秘密种子短语！

   # .env
   # Replace with your actual 12 or 24 word seed phrase (no quotes)
   MNEMONIC="word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12"

   # Set to 'testnet' or 'mainnet'
   NEAR_NETWORK_ID="testnet"

   # Optional: Specify a different RPC node URL if needed
   # NEAR_NODE_URL="https://rpc.testnet.near.org"

1. 构建服务器： 将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 as NEAR MCP Server running on stdio...

在将服务器与客户端一起使用时，保持终端运行。服务器的日志和错误将显示在此终端中（stderr）。

🔑 默认帐户行为

此服务器实现通过以下方式处理帐户ID：

1. 当账户ID被明确地提供给工具功能时（例如。， get_account_balance({ accountId: "example.near" }))，将使用该特定帐户。

1. 当没有提供帐户ID时，服务器将使用自己的帐户（从MNEMONIC派生的帐户）。

1. 如果服务器没有已建立的帐户ID（例如，当为链上尚不存在的帐户使用种子短语时），它将转而使用从种子短语的公钥导出的隐式帐户ID。

这种行为允许工具与明确指定的帐户和服务器自己的帐户无缝协作，提供更好的用户体验。

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

1. 查找克劳德配置： 找到Claude Desktop配置文件：

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

1. 编辑配置： 在以下位置为此服务器添加条目 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"
         }
       }
     }
   }

1. 重新启动Claude： 保存配置文件并完全重新启动Claude Desktop应用程序。

1. 验证连接： 在聊天输入区域中查找锤子图标。单击它应该列出此服务器中定义的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提供的输入（如合约调用或文件路径，如果扩展的话）都经过了适当的清理。
• 速率限制： 对于生产服务器，考虑添加速率限制以防止滥用。

🧪 发展

# 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_desktop_config.json 语法。 - 验证 绝对路径 向 build/index.js 是正确的。 - 完全重新启动克劳德桌面。 - 检查克劳德的MCP日志。

• 工具错误： 检查服务器的终端输出（stderr）是否有来自的特定错误消息 near-api-js 或NEAR网络。常见问题包括余额不足、帐户ID不正确或网络问题。

🤝 贡献

欢迎投稿！如果您有建议或改进，请打开问题或提交拉取请求。

📜 许可证

麻省理工学院