Nimiq MCP

Nimiq MCP Server

A Model Context Protocol (MCP) server for interacting with the Nimiq blockchain.

📖 Model Context Protocol

特性

• 🚀 两种部署选项：零设置远程访问或本地安装
• 🔗 18个综合工具 用于帐户、交易、块、验证器等
• 🤖 MCP 2025-06-18协议：具有增强功能的最新规格
• 💬 交互式工具：引导用户体验的激励支持
• ⚡ 远程选项：无需安装-只需将URL添加到MCP客户端即可
• 🔧 本地选项：完全控制 npx nimiq-mcp
• 🔍 高级搜索：通过全面的Nimiq文档进行全文搜索
• 📊 增强计算：具有智能默认值的交互式质押奖励计算器
• 🔒 只读操作 （出于安全考虑，不支持发送交易）
• ✅ 输入验证：对所有工具输入进行全面的模式验证

快速开始

从两个选项中选择一个：

选项1：远程访问

将此添加到MCP客户端配置中：

{
  "mcpServers": {
    "nimiq": {
      "url": "https://nimiq-mcp.je-cf9.workers.dev/sse",
      "transport": "sse"
    }
  }
}

选项2：本地安装

将此添加到MCP客户端配置中：

{
  "mcpServers": {
    "nimiq": {
      "command": "npx",
      "args": ["nimiq-mcp"]
    }
  }
}

比较

使用自定义RPC端点和身份验证

Remote (SSE)

{
  "mcpServers": {
    "nimiq": {
      "url": "https://nimiq-mcp.je-cf9.workers.dev/sse?rpc-url=https://your-rpc-endpoint.com&rpc-username=your-username&rpc-password=your-password",
      "transport": "sse"
    }
  }
}

Local (npx)

{
  "mcpServers": {
    "nimiq": {
      "command": "npx",
      "args": [
        "nimiq-mcp",
        "--rpc-url",
        "https://your-rpc-endpoint.com",
        "--rpc-username",
        "your-username",
        "--rpc-password",
        "your-password"
      ]
    }
  }
}

可用参数

可用工具和资源

MCP服务器为与Nimiq区块链交互提供了全面的工具和资源：

工具（18个可用）

资源（3个可用）

刀具参数

每个工具都接受特定的参数：

• 块工具: includeBody （boolean）包含交易详细信息
• 地址工具: address Nimiq地址的（字符串）
• 交易工具: hash （字符串）用于交易哈希， max （数字）用于限制
• 文档工具: includeSchemas （布尔值）for getRpcMethods 包括详细的参数/结果模式
• 搜索工具: query （string）用于搜索词， limit （数字）控制结果计数

资源访问

资源通过其URI访问，不需要参数：

• 文献资源：通过访问 nimiq://docs/web-client, nimiq://docs/protocol，或 nimiq://docs/validators
• 内容以纯文本形式返回，以实现最佳的LLM使用
• MCP客户端可以缓存资源内容以提高性能

示例响应

供应数据响应

{
  "total": 210000000000000,
  "vested": 0,
  "burned": 0,
  "max": 210000000000000,
  "initial": 25200000000000,
  "staking": 100000000000,
  "minted": 1000000000,
  "circulating": 25200000000000,
  "mined": 0,
  "updatedAt": "2025-01-20T12:00:00.000Z"
}

阻止数据响应

{
  "blockNumber": 21076071,
  "block": {
    "hash": "90e2ba0a831eec477bca1a26ba8c5e2b3162b5d042667828c4db0f735247d41e",
    "number": 21076071,
    "timestamp": 1749486768481,
    "parentHash": "b4fae3fc846ac13bfc62aa502c8683e25e92616d987f3f642b9cb57da73b6392",
    "type": "micro",
    "producer": {
      "slotNumber": 305,
      "validator": "NQ51 LM8E Q8LS 53TX GGDG 26M4 VX4Y XRE2 8JDT"
    }
  },
  "timestamp": "2025-06-09T16:32:49.055Z",
  "network": "mainnet"
}

搜索文档响应

{
  "query": "validator staking",
  "totalResults": 3,
  "results": [
    {
      "title": "Validator Setup",
      "content": "To become a validator in Nimiq, you need to stake NIM tokens...",
      "section": "Validators",
      "score": 0.95,
      "snippet": "...validator in Nimiq, you need to stake NIM tokens and run validator software..."
    },
    {
      "title": "Staking Rewards",
      "content": "Validators earn rewards for producing blocks and validating transactions...",
      "section": "Economics",
      "score": 0.87,
      "snippet": "...earn rewards for producing blocks and validating transactions. Staking rewards..."
    }
  ],
  "searchedAt": "2025-01-20T12:00:00.000Z"
}

使用示例

Claude桌面配置

选项1：远程（零点设置）

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "nimiq": {
      "url": "https://nimiq-mcp.je-cf9.workers.dev/sse",
      "transport": "sse"
    }
  }
}

选项2：本地安装

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "nimiq": {
      "command": "npx",
      "args": ["nimiq-mcp"]
    }
  }
}

使用自定义本地配置

{
  "mcpServers": {
    "nimiq": {
      "command": "npx",
      "args": [
        "nimiq-mcp",
        "--rpc-url",
        "https://rpc.nimiqwatch.com"
      ]
    }
  }
}

在Web应用程序中

通过HTTP直接访问远程服务器：

// Connect to the remote MCP server
const mcpClient = new SSEClientTransport(
  new URL('https://nimiq-mcp.je-cf9.workers.dev/sse')
)

在其他MCP客户端中

服务器遵循MCP规范，可以与任何兼容MCP的客户端一起使用：

本地安装：

npx nimiq-mcp

远程访问：

• 工具端点: https://nimiq-mcp.je-cf9.workers.dev/tools
• 信息端点: https://nimiq-mcp.je-cf9.workers.dev/info
• 健康检查: https://nimiq-mcp.je-cf9.workers.dev/health
• web界面: https://nimiq-mcp.je-cf9.workers.dev/

发展

地方发展

# Install dependencies
pnpm install

# Run linting
pnpm run lint

# Fix linting issues
pnpm run lint:fix

# Build for production
pnpm run build

# Test the server manually
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

Cloudflare员工发展

# Install dependencies including Wrangler
pnpm install

# Start local development server
pnpm run dev:worker

# Build and test worker deployment
pnpm run build:worker

# Deploy to Cloudflare
pnpm run deploy

部署到Cloudflare Workers

查看完整 部署指导 详细说明。

快速部署步骤：

1. 建立Cloudflare账户，获取API代币
2. 配置GitHub机密 （用于自动部署）：

- CLOUDFLARE_API_TOKEN - CLOUDFLARE_ACCOUNT_ID

1. 推送到主分支 -通过GitHub Actions自动部署
2. 配置生产机密 （可选）：

   wrangler secret put NIMIQ_RPC_URL
   wrangler secret put NIMIQ_RPC_USERNAME
   wrangler secret put NIMIQ_RPC_PASSWORD

工人将在以下地点工作： https://nimiq-mcp.je-cf9.workers.dev

建筑

MCP服务器是使用以下方式构建的：

• @模型上下文协议/sdk：TypeScript官方MCP SDK
• nimiq-rpc客户端ts：全类型Nimiq RPC客户端
• rpc.nimiqwatch.com：免费公共Nimiq RPC服务
• 瓦利博：所有工具输入的运行时模式验证和类型安全
• Cloudflare员工：用于远程部署的边缘计算平台
• TypeScript：用于类型安全和更好的开发经验

MCP 2025-06-18协议特征

此服务器实现了最新的模型上下文协议规范（2025-06-18），具有增强的功能：

• 激励支持：交互式工具可以在执行过程中向用户请求其他信息
• 增强的输入验证：具有详细错误消息的全面架构验证
• 结构化工具响应：JSON模式定义，以更好地理解LLM
• 改进了错误处理：具有适当MCP错误代码的标准化错误响应
• 协议版本合规性：完全支持最新的MCP规范要求

部署选项

本地部署（STDIO传输）

• 作为通过stdin/stdout通信的本地进程运行
• 最适合桌面应用程序和本地开发
• 无需网络配置
• 固有安全（无网络暴露）

远程部署（SSE传输）

• 部署在Cloudflare Workers边缘网络上
• 可通过HTTPS从任何地方访问
• 支持多个并发客户端
• 内置安全性、速率限制和全局CDN
• 自动扩展和高可用性

输入验证

服务器使用 瓦利博 为了对所有工具进行全面的输入验证，提供：

• 运行时类型安全：所有工具输入都根据严格的模式进行验证
• 描述性错误消息：使用字段级详细信息清除验证错误
• 类型推断：从Valibot模式自动推断TypeScript类型
• 默认值：自动应用可选参数的默认值
• 枚举验证：严格验证网络类型等参数的允许值

验证示例：

const StakingRewardsSchema = v.object({
  amount: v.optional(v.pipe(v.number(), v.description('Initial amount staked in NIM')), 1),
  days: v.optional(v.pipe(v.number(), v.description('Number of days staked')), 365),
  network: v.optional(v.pipe(v.picklist(['main-albatross', 'test-albatross']), v.description('Network name')), 'main-albatross'),
})

错误处理

服务器包括全面的错误处理：

• RPC连接错误
• 费率限制处理
• 无效参数
• 网络超时
• SIGINT上的优雅关机

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行测试和梳理
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。