内容
# 🌊 NEAR MCP 服务器
[](https://www.npmjs.com/package/@iqai/mcp-near)
[](https://opensource.org/licenses/ISC)
## 📖 概述
NEAR MCP 服务器使 AI 代理能够与 [NEAR 协议](https://near.org) 区块链进行交互。该服务器提供智能合约交互、交易处理和事件监听能力，并支持 AI 驱动的处理。
通过实施模型上下文协议（MCP），该服务器允许大型语言模型（LLM）监控区块链事件，使用 AI 智能处理它们，并返回到智能合约，弥合 AI 和去中心化应用之间的差距。
## ✨ 功能
* **事件监听**：实时监控 NEAR 智能合约的特定事件。
* **AI 驱动处理**：自动使用 AI 处理区块链事件，并向合约发送响应。
* **订阅管理**：管理多个事件订阅，并附带详细统计信息。
* **灵活配置**：可自定义的轮询间隔、响应方法和网络设置。
## 📦 安装
### 🚀 使用 npx（推荐）
无需全局安装即可使用此服务器：
```bash
npx @iqai/mcp-near
```
### 🔧 从源码构建
```bash
git clone https://github.com/IQAIcom/mcp-near.git
cd mcp-near
pnpm install
pnpm run build
```
## ⚡ 使用 MCP 客户端运行
在您的 MCP 客户端设置中添加以下配置（例如 `claude_desktop_config.json`）。
### 📋 最简配置
```json
{
"mcpServers": {
"near": {
"command": "npx",
"args": ["-y", "@iqai/mcp-near"],
"env": {
"ACCOUNT_ID": "your-account.near",
"ACCOUNT_KEY": "ed25519:your_private_key_here"
}
}
}
}
```
### ⚙️ 高级配置（本地构建）
```json
{
"mcpServers": {
"near": {
"command": "node",
"args": ["/absolute/path/to/mcp-near/dist/index.js"],
"env": {
"ACCOUNT_ID": "your-account.near",
"ACCOUNT_KEY": "ed25519:your_private_key_here",
"NEAR_NETWORK_ID": "mainnet",
"NEAR_NODE_URL": "https://rpc.mainnet.near.org"
}
}
}
}
```
## 🔐 配置（环境变量）
| 变量 | 是否必需 | 描述 | 默认值 |
| :--- | :--- | :--- | :--- |
| `ACCOUNT_ID` | 是 | 用于身份验证的 NEAR 账户 ID | - |
| `ACCOUNT_KEY` | 是 | NEAR 账户的私钥（ed25519: 或 secp256k1: 格式） | - |
| `NEAR_NETWORK_ID` | 否 | NEAR 网络（"mainnet", "testnet", "betanet"） | `mainnet` |
| `NEAR_NODE_URL` | 否 | 自定义 NEAR RPC 端点 | - |
| `NEAR_GAS_LIMIT` | 否 | 交易的 gas 限制 | - |
## 💡 使用示例
### 🔔 事件监听
* "监听合约 oracle.near 上的 'run_agent' 事件"
* "开始监控 my-contract.testnet 上的 price_request 事件"
* "设置一个监听 transfer 事件的监听器，轮询间隔为 5 秒"
### 📊 订阅管理
* "列出所有我的活动事件订阅"
* "显示我的事件监听器的统计信息"
* "停止监听合约 oracle.near 上的事件"
### 🤖 AI 驱动工作流
* "处理 incoming oracle 请求并用 AI 分析响应"
* "监听用户查询并提供智能响应"
## 🛠️ MCP 工具
<!-- AUTO-GENERATED TOOLS START -->
<!-- AUTO-GENERATED TOOLS END -->
## 👨💻 开发
### 🏗️ 构建项目
```bash
pnpm run build
```
### 👁️ 开发模式（监听）
```bash
pnpm run watch
```
### ✅ 校验和格式化
```bash
pnpm run lint
pnpm run format
```
### 🧪 运行测试
```bash
pnpm test
```
### 📁 项目结构
* `src/tools/`: 独个工具定义
* `src/services/`: 事件监听器、身份管理器和业务逻辑
* `src/types.ts`: TypeScript 类型定义
* `src/index.ts`: 服务器入口点
## 🔄 AI 驱动事件处理工作流
服务器启用了 "AI 在循环中" 的工作流：
1. 🔗 智能合约交易触发事件并暂停执行
2. 🤖 MCP 服务器检测到事件并向 AI 客户端请求 AI 处理
3. 🧠 AI 客户端处理事件数据并提供智能响应
4. ↩️ 服务器通过交易将 AI 响应发送回区块链
5. ✅ 原始智能合约使用 AI 提供的数据恢复
## 📚 资源
* [NEAR 协议文档](https://docs.near.org)
* [模型上下文协议（MCP）](https://modelcontextprotocol.io)
* [NEAR JavaScript API](https://github.com/near/near-api-js)
## ⚠️ 免责声明
该项目与 NEAR 区块链交互，需要私钥进行交易签名。用户应谨慎操作，确保凭证安全，并独立验证所有交易。区块链操作涉及风险，可能产生 gas 费用。
## 📄 许可证
[ISC](LICENSE)
