qubic-mcp

qubic-mcp

Qubic 暗号資産向けの MCP サーバー — AI アシスタントが Qubic ネットワークを操作できるようにします。

概要

qubic-mcp は、AI アシスタント（Claude、ChatGPT、Copilot、Cursor など）が Qubic ブロックチェーンにネイティブにアクセスできるようにする、オープンソースの Model Context Protocol（MCP） サーバーです。

自然言語で、残高の照会、トランザクションの確認、ネットワークの監視、QX での取引、ネットワークの切り替え、スマートコントラクトとのやり取りができます。

v0.4 の新機能

• スマートコントラクトプロファイル — カスタムの SC インターフェース定義を登録すると、自動的なバイナリーのエンコード／デコードにより名前で照会できます
• ネットワーク管理 — メインネット、テストネット、独自のローカル／ライトノードを保存し、実行時に切り替えられます
• エポック計算ノード — 任意のエポックの 676 個の計算ノード ID を照会できます
• MCP プロンプト — ポートフォリオ分析、市場概要、調査用の定義済みワークフロー
• MCP リソース — Qubic の参考ドキュメント（ネットワーク、トークノミクス、スマートコントラクト、アドレス形式）
• HTTP トランスポート — リモート環境へのデプロイ用に、スタンドアロンの HTTP サーバーとして実行できます

機能

ブロックチェーン照会ツール

• 残高と送金 — 任意の Qubic アドレスの残高と送金履歴を照会します
• トランザクション — ID からトランザクションの詳細を検索します
• ネットワーク状況 — 現在のティック、エポック、供給量、バーン済み QUs、アクティブアドレス、時価総額
• マイニングフェーズ — 現在の MINING／IDLE フェーズ、サイクルの進捗状況、XMR マラソンの状況
• エポック計算ノード — 指定したエポックの 676 個すべての計算ノード ID を一覧表示します
• リッチリスト — 残高順の上位保有者

市場と分析

• トークン価格 — 3 つのソース（CoinGecko、Qubic API、CryptoCompare）で比較した QUBIC のリアルタイム価格
• QU/USD コンバーター — ライブレートで QU と USD を相互に換算します
• トークンレジストリ — 発行者とウェブサイトを含む、登録済み Qubic トークンの一覧
• QX DEX オーダーブック — QX 分散型取引所における任意のトークンの売り注文と買い注文をリアルタイムで表示します

スマートコントラクトツール

• コントラクトの登録 — カスタム SC インターフェース定義（関数名、入力／出力フィールドのスキーマ）を保存します
• コントラクトの照会 — 自動的なバイナリーのエンコード／デコードにより、登録済み SC 関数を名前で照会します
• 生の SC 照会 — 高度な用途向けの、base64 入出力を使用する低レベルのスマートコントラクト照会
• コントラクトの一覧表示／削除 — 登録済みのコントラクト定義を管理します

ローカル管理

• ウォレット管理 — ウォレットアドレスをローカルに保存して、すばやくアクセスできます
• ネットワーク切り替え — メインネット、テストネット、カスタム RPC エンドポイントを保存し、実行時に切り替えられます
• アドレス検証 — 形式とオンチェーンでのアクティビティを確認します
• エクスプローラーリンク — Qubic 公式ブロックエクスプローラーへの直接リンク

AI コンテキスト

• MCP リソース — コンテキストとして利用できる Qubic の参考ドキュメント（ネットワーク、トークノミクス、スマートコントラクト、アドレス形式）
• MCP プロンプト — ポートフォリオ分析、市場概要、Qubic の調査用の定義済みワークフロー

クイックスタート

Claude、ChatGPT、Copilot、Cursor、Windsurf、Gemini、JetBrains など、MCP 互換の AI クライアントならどれでも使えます。

クライアントの 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 の最も強力な機能の 1 つが、スマートコントラクトプロファイルシステムです。ローカルの 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 サーバーは、mainnet の代わりにローカルの 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. 完了したら mainnet に戻します。

"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 — mainnet、testnet、または保存済みのネットワーク間で切り替えます
3. ネットワークを一覧表示： list_networks — 利用可能なすべてのネットワークと、現在アクティブなネットワークを確認します

ネットワークは ~/.qubic-mcp/networks.json に保存され、セッションをまたいで保持されます。組み込みネットワーク（mainnet、testnet）は常に利用できます。

環境変数

高度な用途や CI 環境では、環境変数を使って設定することもできます。.env.example を参照してください。

変数	デフォルト	説明
QUBIC_RPC_URL	(アクティブなネットワークから取得)	RPC エンドポイントを上書きします（保存済みネットワークより優先されます）
QUBIC_API_URL	(アクティブなネットワークから取得)	Query API エンドポイントを上書きします
QUBIC_NETWORK_LABEL	(自動)	QUBIC_RPC_URL で上書きした際に表示される分かりやすいラベル
MCP_HTTP_PORT	(未設定)	stdio の代わりに HTTP サーバーとして実行するポートを設定します

HTTP トランスポート

デフォルトでは、サーバーは stdio を使用します。これはほとんどの MCP クライアントが想定する方式です。代わりにスタンドアロンの HTTP エンドポイントとして実行するには、MCP_HTTP_PORT を設定します。

MCP_HTTP_PORT=3000 node dist/index.js

サーバーは、MCP Streamable HTTP トランスポートに対応する単一の /mcp エンドポイントを公開します。

• POST /mcp — JSON-RPC リクエストを送信します（initialize によってセッションが作成されます）
• GET /mcp — サーバー通知用の SSE ストリームを開きます（mcp-session-id ヘッダーが必要です）
• DELETE /mcp — セッションを終了します

すべてのツール

ブロックチェーン

ツール	説明
get_balance	アドレスまたは保存済みウォレットの残高と送金履歴を取得します
get_tick_info	現在の tick 番号、エポック、tick の長さを取得します
get_network_status	ネットワーク統計情報：供給量、焼却済み QU、アクティブアドレス数、tick 品質、時価総額
get_transaction	60 文字の ID でトランザクションを検索します
get_transfer_history	tick の範囲を指定して、アドレスのページ分割された送金履歴を取得します
get_mining_phase	現在の MINING／IDLE フェーズ、サイクルの進行状況、XMR マラソンの状態を取得します
get_epoch_computors	指定したエポックの 676 件すべての computor ID を一覧表示します
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 node など）を保存し、すばやく切り替えられるようにします
switch_network	アクティブなネットワークを切り替えます（mainnet、testnet、または保存済みのカスタムネットワーク）
list_networks	利用可能なネットワークをすべて一覧表示し、現在アクティブなネットワークを示します
remove_network	保存済みのカスタムネットワークを削除します

ユーティリティ

ツール	説明
validate_address	アドレスの形式を検証し、オンチェーンのアクティビティを確認します
get_explorer_links	アドレスまたはトランザクションの Qubic ブロックエクスプローラーへのリンクを取得します

MCP リソース

リソース URI	説明
qubic://docs/network	Qubic ネットワーク：エポック、ティック、クォーラムコンセンサス、コンピューターランキング
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 のティックと並行処理：ティックのライフサイクル、並列実行、トランザクションの順序付け
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 ブロックチェーンと連携します。すべての情報を確認し、リスクを理解する責任はユーザー自身にあります。このソフトウェアは金融に関する助言を提供するものではありません。