AI导哈

区块链AI助手服务

qubic-mcp是一个开源模型上下文协议服务器，使AI助手能够通过自然语言与Qubic区块链网络交互，包括查询余额、交易、网络状态、智能合约等功能。

  • by fyllepo
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 fyllepo/qubic-mcp

使用说明

量子微控制器

Qubic加密货币的MCP服务器——使AI助手能够与Qubic网络进行交互。

概述

量子微控制器 是一个开源 模型上下文协议（MCP） 为人工智能助手（Claude、ChatGPT、Copilot、Cursor等）提供本地访问权限的服务器 多层式四子棋 块链。

查询余额、检查交易、监控网络、在QX上交易、在网络之间切换以及与智能合约交互——所有这些都是通过自然语言完成的。

v0.4的新增功能

  • 智能合约配置文件 --注册自定义SC接口定义，然后通过自动二进制编码/解码按名称查询它们
  • 网络管理 --在运行时保存并在主网、测试网或您自己的本地/lite节点之间切换
  • **** --查询任何纪元的676个计算机标识
  • MCP提示 --用于投资组合分析、市场概述和研究的预定义工作流程
  • MCP资源 --Qubic参考文档（网络、代币经济学、智能合约、地址格式）
  • HTTP传输 --作为独立的HTTP服务器运行以进行远程部署

特性

区块链查询工具

  • 余额和转账 --查询任何Qubic地址余额和转账历史
  • 交易 --按ID查找交易详细信息
  • 网络状态 --当前分时、纪元、供应量、已销毁的QU、有效地址、市值
  • 采矿阶段 --当前采矿/空闲阶段、循环进度和XMR马拉松状态
  • **** --列出给定纪元的所有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"]
    }
  }
}
Where to find the config file
客户端 配置位置
克劳德桌面版 （macOS） ~/Library/Application Support/Claude/claude_desktop_config.json
克劳德桌面版 （Windows） %APPDATA%\Claude\claude_desktop_config.json
克劳德桌面版 （Linux） ~/.config/Claude/claude_desktop_config.json
克劳德代码 快跑 claude mcp add qubic -- npx mcp-server-qubic 在您的终端
VS代码/光标/风帆 .vscode/mcp.json 或编辑器的MCP设置
JetBrains集成开发环境 设置>工具>AI助手>MCP服务器
ChatGPT桌面 设置>MCP服务器>添加

对于其他客户端，请查看应用程序的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"

智能合约开发工作流程

量子比特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服务器现在与您的本地精简节点而不是主网通信。这在以下会话中持续存在 ~/.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)

助理会打电话来 register_contract 使用正确的字段模式JSON。定义保存到 ~/.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网络通信的最简单方法是通过内置工具——不需要env变量：

  1. 添加自定义网络： add_network --用友好名称保存本地节点的IP
  2. 交换网络： switch_network --在主网、测试网或任何已保存的网络之间切换
  3. 列出网络： list_networks --查看所有可用网络以及哪个网络处于活动状态

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

环境变量

对于高级使用或CI环境，您还可以通过env-vars进行配置。看 .env.example.

变量 默认值 描述
QUBIC_RPC_URL （来自活动网络） 覆盖RPC终结点（优先于已保存的网络）
QUBIC_API_URL （来自活动网络） 覆盖查询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流式HTTP传输的端点：

  • POST/mcp --发送JSON-RPC请求（初始化创建会话）
  • GET/mcp --打开服务器通知的SSE流（需要 mcp-session-id 头球
  • 删除/mcp --终止会话

所有工具

区块链

工具 说明
get_balance 获取地址或已保存钱包的余额和转账活动
get_tick_info 获取当前滴答数、纪元和滴答持续时间
get_network_status 网络统计数据：供应量、烧毁的QU、活动地址、报价质量、市值
get_transaction 通过60个字符的ID查找交易
get_transfer_history 勾选范围内地址的分页传输历史记录
get_mining_phase 当前采矿/空闲阶段、循环进度和XMR马拉松状态
get_epoch_computors 列出给定纪元的所有676个计算机标识
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 使用原始base64输入/输出的低级SC查询
list_contracts 列出所有已注册的合同定义
remove_contract 删除已注册的合同定义

钱包

工具 说明
save_wallet 用友好的名称保存Qubic地址，以便快速访问
list_wallets 列出所有已保存的钱包
remove_wallet 删除已保存的钱包

网络管理

工具 说明
add_network 保存自定义Qubic网络（例如本地lite节点）以进行快速切换
switch_network 切换活动网络（主网、测试网或任何已保存的自定义网络）
list_networks 列出所有可用网络并显示当前处于活动状态的网络
remove_network 删除已保存的自定义网络

效用

工具 说明
validate_address 验证地址格式并检查链活动
get_explorer_links 获取地址或交易的Qubic区块浏览器链接

MCP资源

资源URI 描述
qubic://docs/network Qubic网络：纪元、滴答声、法定人数共识、计算机排名
qubic://docs/tokenomics 量子代币经济学：供应上限、排放时间表、燃烧
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滴答和并发：滴答生命周期、并行执行、事务排序
qubic://docs/interact-sc 与Qubic智能合约交互：调用函数、调用过程
qubic://docs/execution-fees Qubic合同执行费：费用准备金、调用成本、烧录机制
qubic://docs/rpc Qubic RPC API：端点、智能合约查询、事务广播
qubic://docs/qpi Qubic协议接口（QPI）：可用于智能合约的API

MCP提示

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

本地数据

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

文件 目的
wallets.json 保存的钱包地址（仅限公共地址，从不包括私钥）
networks.json 已保存的网络配置文件和活动网络选择
contracts.json 已注册的智能合约接口定义

安全

这个项目非常重视安全性，特别是考虑到它与金融网络的交互。

  • 没有私钥 --此服务器是只读的。它从不要求、存储或传输私钥或种子。
  • 输入验证 --在处理之前，所有输入都使用Zod模式进行验证。
  • 无遥测 --没有任何类型的分析、跟踪或数据收集。
  • 可审计的 --完全开源。读每一行。

看 安全.md 我们的漏洞披露政策。

贡献

欢迎并鼓励捐款！无论您是在修复错误、添加新工具、改进文档还是提出想法，我们都希望您的帮助。

看 贡献.md 作为指导方针。

路线图

看 ROADMAP.md 我们计划的功能和未来方向。

许可证

麻省理工学院——见 许可证.

免责声明

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

该工具与Qubic区块链交互，交易是不可逆的。用户全权负责验证所有信息并了解风险。该软件不提供财务建议。

相关 MCP