qubic-mcp

qubic-mcp

用于 Qubic 加密货币的 MCP 服务 — 让 AI 助手能够与 Qubic 网络交互。

概述

qubic-mcp 是一个开源的 Model Context Protocol (MCP) 服务，为 AI 助手 — Claude、ChatGPT、Copilot、Cursor 等 — 提供对 Qubic 区块链的原生访问能力。

通过自然语言查询余额、查看交易、监控网络、在 QX 上交易、切换网络并与智能合约交互。

v0.4 新增功能

• 智能合约配置 — 注册自定义 SC 接口定义，然后按名称查询，并自动进行二进制编码／解码
• 网络管理 — 保存并在运行时切换主网、测试网或自有本地／轻节点
• Epoch 计算器 — 查询任意 epoch 的 676 个计算器身份
• MCP 提示词 — 用于投资组合分析、市场概览和研究的预定义工作流
• MCP 资源 — Qubic 参考文档（网络、代币经济学、智能合约、地址格式）
• HTTP 传输 — 作为独立 HTTP 服务运行，以便远程部署

功能

区块链查询工具

• 余额与转账 — 查询任意 Qubic 地址的余额和转账历史
• 交易 — 按 ID 查询交易详情
• 网络状态 — 当前 tick、epoch、供应量、已销毁 QUs、活跃地址、市值
• 挖矿阶段 — 当前 MINING／IDLE 阶段、周期进度和 XMR 马拉松状态
• Epoch 计算器 — 列出指定 epoch 的全部 676 个计算器身份
• 富豪榜 — 按余额排名的顶级持有者

市场与分析

• 代币价格 — 实时比较 3 个来源的 QUBIC 价格（CoinGecko、Qubic API、CryptoCompare）
• QU／USD 转换器 — 按实时汇率在 QU 和 USD 之间转换
• 代币注册表 — 列出所有已注册的 Qubic 代币及其发行方和网站
• QX DEX 订单簿 — 查询 QX 去中心化交易所中任意代币的实时卖单／买单

智能合约工具

• 注册合约 — 保存自定义 SC 接口定义（函数名称、输入／输出字段架构）
• 查询合约 — 按名称查询已注册的 SC 函数，并自动进行二进制编码／解码
• 原始 SC 查询 — 通过 base64 输入／输出进行底层智能合约查询，适用于高级用途
• 列出／移除合约 — 管理已注册的合约定义

本地管理

• 钱包管理 — 在本地保存钱包地址，以便快速访问
• 网络切换 — 保存并在运行时切换主网、测试网或自定义 RPC 端点
• 地址验证 — 检查格式和链上活动
• 区块浏览器链接 — 直达 Qubic 官方区块浏览器的链接

AI 上下文

• MCP 资源 — 可用作上下文的 Qubic 参考文档（网络、代币经济学、智能合约、地址格式）
• MCP 提示词 — 预定义工作流：投资组合分析、市场概览和 Qubic 研究

快速开始

适用于任何兼容 MCP 的 AI 客户端，包括 Claude、ChatGPT、Copilot、Cursor、Windsurf、Gemini、JetBrains 等。

将以下内容添加到客户端的 MCP 配置中：

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

在哪里可以找到配置文件

客户端	配置位置
Claude Desktop（macOS）	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop（Windows）	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop（Linux）	~/.config/Claude/claude_desktop_config.json
Claude Code	在终端中运行 claude mcp add qubic -- npx mcp-server-qubic
VS Code / Cursor / Windsurf	.vscode/mcp.json 或编辑器的 MCP 设置
JetBrains IDEs	Settings > Tools > AI Assistant > MCP Servers
ChatGPT Desktop	Settings > MCP Servers > Add

其他客户端请查看应用的 MCP 文档——上述配置通用。

然后直接用自然语言提问：

钱包管理

"Save my wallet UXITJAGNXUE...RAPDBE as my-main"
"List my wallets"
"Remove my old-wallet"

余额与转账

"What's the balance of my-main?"
"Show transfer history for my-main over the last 1000 ticks"

价格与市场

"What's the current QUBIC price?"
"How much is 1 billion QU worth in USD?"
"Convert $100 to QU"

网络与挖矿

"What's the current tick?"
"Show me the network status"
"What mining phase are we in?"
"Who are the top Qubic holders?"

QX DEX 与代币

"What tokens are available on Qubic?"
"Show the QX orderbook for CFB"
"Show bid orders for QMINE on QX"

网络切换

"Add my local network at http://192.168.1.50:21841"
"Switch to my local network"
"Switch back to mainnet"
"List my networks"

智能合约查询

"Register my counter contract at index 10 with these functions: [...]"
"Query counter getStats"
"Query counter getValue with key 1"
"List my registered contracts"

智能合约开发工作流

qubic-mcp 最强大的功能之一是智能合约配置文件系统。如果你正在本地 lite 网络上开发 Qubic 智能合约，可以通过 MCP 使用 AI 助手直接测试合约的 RPC 接口。

为什么这很重要

Qubic 智能合约通过 /v1/querySmartContract RPC 端点，以二进制编码的结构体进行通信。没有工具支持时，你需要手动将字段编码为 base64、发起 HTTP 请求并解码二进制响应——这既繁琐又容易出错。

使用 qubic-mcp，只需注册一次合约接口，之后就可以通过名称查询，并使用人类可读的输入和输出。AI 助手会自动处理所有二进制编码和解码。

分步操作

1. 将 MCP 指向你的测试网络：

"Add my test network at http://192.168.1.50:21841 called my-testnet"
"Switch to my-testnet"

现在，MCP 服务会与本地 lite 节点通信，而非主网。此设置会保存到 ~/.qubic-mcp/networks.json，并在各会话间保留。

2. 注册合约接口：

告诉助手合约的索引和函数定义。以下以索引为 10 的简单计数器合约为例：

Register my counter contract at index 10 with these functions:

- getStats (inputType 1): no input, output is totalKeys (uint32) and totalIncrements (uint64)
- getValue (inputType 2): input is key (uint32), output is value (uint64) and lastUpdatedTick (uint32)

助手会使用正确的字段架构 JSON 调用 register_contract。定义会保存到 ~/.qubic-mcp/contracts.json，并在各会话间保留。

支持的字段类型： uint8、uint16、uint32、uint64、int8、int16、int32、int64、identity（60 个字符的 Qubic 地址 / 32 字节公钥）、padding（跳过的字节）。

字段支持用于数组的 count，以及用于值到标签映射的 enum。

3. 按名称查询合约：

"Query counter getStats"
"Query counter getValue with key 1"

MCP 会将输入编码为二进制，调用 RPC 端点，并将响应解码为命名字段：

counter.getValue
================

  value: 42
  lastUpdatedTick: 22,345,678

4. 完成后切回主网：

"Switch to mainnet"

安装

从 npm 安装（推荐）

npm install -g mcp-server-qubic

从源代码安装

git clone https://github.com/fyllepo/qubic-mcp.git
cd qubic-mcp
npm install
npm run build

配置

网络管理

配置要连接的 Qubic 网络，最简单的方法是使用内置工具——无需环境变量：

1. 添加自定义网络： add_network——保存本地节点的 IP 并为其指定一个易记的名称
2. 切换网络： switch_network——在主网、测试网或任何已保存的网络之间切换
3. 列出网络： list_networks——查看所有可用网络及当前激活的网络

网络会保存到 ~/.qubic-mcp/networks.json，并在各会话间保留。内置网络（主网、测试网）始终可用。

环境变量

如需高级用途或用于 CI 环境，也可以通过环境变量进行配置。请参阅 .env.example。

变量	默认值	描述
QUBIC_RPC_URL	（来自当前网络）	覆盖 RPC 端点（优先级高于已保存的网络）
QUBIC_API_URL	（来自当前网络）	覆盖 Query API 端点
QUBIC_NETWORK_LABEL	（自动）	使用 QUBIC_RPC_URL 覆盖时显示的易读标签
MCP_HTTP_PORT	（未设置）	设置端口，以 HTTP 服务而非 stdio 方式运行

HTTP 传输

默认情况下，服务使用 stdio，这是大多数 MCP 客户端所期望的方式。如需将其作为独立的 HTTP 端点运行，请设置 MCP_HTTP_PORT：

MCP_HTTP_PORT=3000 node dist/index.js

服务提供一个 /mcp 端点，支持 MCP Streamable HTTP 传输：

• POST /mcp — 发送 JSON-RPC 请求（initialize 会创建会话）
• GET /mcp — 打开用于接收服务通知的 SSE 流（需要 mcp-session-id 标头）
• DELETE /mcp — 终止会话

所有工具

区块链

工具	描述
get_balance	获取某个地址或已保存钱包的余额和转账活动
get_tick_info	获取当前 tick 编号、epoch 和 tick 时长
get_network_status	网络统计：供应量、已销毁的 QUs、活跃地址、tick 质量、市值
get_transaction	通过 60 个字符的 ID 查找交易
get_transfer_history	获取某个地址在指定 tick 范围内的分页转账历史
get_mining_phase	获取当前 MINING/IDLE 阶段、周期进度和 XMR 马拉松状态
get_epoch_computors	列出指定 epoch 的全部 676 个 computor 身份
get_rich_list	按余额排名的 Qubic 地址列表，支持分页

市场与代币

工具	描述
get_token_price	对比 CoinGecko、Qubic API 和 CryptoCompare 上的 QUBIC 价格
convert_qu_usd	使用实时价格在 QU 和 USD 之间换算
get_token_list	列出所有已注册的 Qubic 代币及其名称、发行方地址和网站
get_qx_orderbook	QX DEX 订单簿 — 任意代币的卖单和／或买单，支持分页

智能合约开发与测试

工具	描述
register_contract	注册带有类型化函数架构的自定义 SC 定义
query_contract	按名称查询已注册的 SC 函数（自动进行二进制编码／解码）
query_smart_contract	低级 SC 查询，使用原始 base64 输入／输出
list_contracts	列出所有已注册的合约定义
remove_contract	移除已注册的合约定义

钱包

工具	描述
save_wallet	保存 Qubic 地址并为其指定易读名称，以便快速访问
list_wallets	列出所有已保存的钱包
remove_wallet	移除已保存的钱包

网络管理

工具	描述
add_network	保存自定义 Qubic 网络（例如本地轻节点），以便快速切换
switch_network	切换当前网络（mainnet、testnet 或任意已保存的自定义网络）
list_networks	列出所有可用网络并显示当前激活的网络
remove_network	移除已保存的自定义网络

实用工具

工具	描述
validate_address	验证地址格式并检查链上活动
get_explorer_links	获取指向 Qubic 区块浏览器的链接，可用于地址或交易

MCP 资源

资源 URI	描述
qubic://docs/network	Qubic 网络：周期、tick、法定人数共识、计算机排名
qubic://docs/tokenomics	Qubic 代币经济学：供应上限、发行计划、销毁
qubic://docs/smart-contracts	Qubic 智能合约：治理、执行、IPO 流程
qubic://docs/address-format	Qubic 身份系统：从种子到私钥，再到公钥和地址
qubic://docs/oracles	Qubic Oracle Machines：通过 QPI 将智能合约与现实世界数据连接起来
qubic://docs/sc-architecture	Qubic 智能合约架构：状态、过程、函数、日志记录
qubic://docs/sc-lifecycle	智能合约生命周期：从研究到提案、IPO、部署和维护
qubic://docs/ticks-concurrency	Qubic tick 与并发：tick 生命周期、并行执行、交易排序
qubic://docs/interact-sc	与 Qubic 智能合约交互：调用函数、执行过程
qubic://docs/execution-fees	Qubic 合约执行费用：费用储备、调用成本、销毁机制
qubic://docs/rpc	Qubic RPC API：端点、智能合约查询、交易广播
qubic://docs/qpi	Qubic Protocol Interface（QPI）：智能合约可用的 API

MCP 提示词

提示词	描述
qubic-portfolio	分析你的投资组合：钱包余额、代币持有量、美元价值
qubic-market	市场概览：价格、网络统计数据、挖矿阶段、富豪榜
qubic-research	使用内置参考文档研究 Qubic 主题

本地数据

qubic-mcp 将本地数据存储在 ~/.qubic-mcp/ 中：

文件	用途
wallets.json	已保存的钱包地址（仅公开地址，不会保存私钥）
networks.json	已保存的网络配置和当前选中的网络
contracts.json	已注册的智能合约接口定义

安全

本项目高度重视安全，尤其是考虑到它会与金融网络交互。

• 无私钥 — 此服务为只读服务。它绝不会索取、存储或传输私钥或种子。
• 输入验证 — 所有输入在处理前都会通过 Zod 架构进行验证。
• 无遥测 — 不进行任何分析、跟踪或数据收集。
• 可审计 — 完全开源。每一行代码都可查阅。

请参阅 SECURITY.md 了解我们的漏洞披露政策。

贡献

欢迎并鼓励贡献！无论你是在修复错误、添加新工具、改进文档，还是提出想法，我们都期待你的帮助。

请参阅 CONTRIBUTING.md 了解贡献指南。

路线图

请参阅 ROADMAP.md 了解我们计划推出的功能和未来方向。

许可证

MIT — 请参阅 LICENSE。

免责声明

本软件按“原样”提供，不附带任何形式的保证。对于因使用本软件而导致的资金、数据或其他损失，作者和贡献者均不承担责任。

此工具会与 Qubic 区块链交互，而该区块链上的交易不可撤销。用户须自行负责核实所有信息并了解相关风险。本软件不提供财务建议。