qnexus-mcp

qnexus-mcp

Quantinuum Nexus 向けのコミュニティ製 Model Context Protocol（MCP）サーバーです。公式の qnexus Python SDK をラップしており、MCP に対応したエージェント（Claude Code、Cursor、VS Code、Codex など）が Nexus を調べたり、オプトインで無料エミュレーター上で回路を実行したりできます。

Quantinuum との提携、同社による承認、または同社の公式製品ではありません。「Quantinuum」と「Nexus」はそれぞれの所有者の商標であり、ここでは互換性を説明する目的で名称を使用しています。

ステータス

開発初期段階です。**デフォルトでは読み取り専用です。**設計とその根拠については docs/DESIGN.md を、背景にある調査については docs/research/ をご覧ください。

要件

• Python 3.10+ と uv（uvx コマンド）。Windows では、uvx.exe の フルパスを控えておいてください（ターミナルで where uvx を実行）。GUI クライアントにはシェルの PATH が引き継がれません。
• Quantinuum Nexus のアカウント。

1. 認証する（初回のみ）

qnexus-mcp は Nexus トークンを扱いません。 qnexus CLI を使って別途認証してください （ブラウザーが開きます）。

uvx --from qnexus qnx login

Nexus JupyterHub 内では認証が自動で行われるため、そこで qnx login を実行しないでください。

2. MCP クライアントにサーバーを追加する

起動コマンドはどのクライアントでも同じです。異なるのはクライアントごとの設定ファイルだけです。

uvx qnexus-mcp==0.2.0                              # read-only (default)
uvx qnexus-mcp==0.2.0 --toolsets read,execute      # + run circuits on the free H2-1LE emulator

バージョンを固定してください（==0.2.0）。固定しない場合、uvx は起動のたびに最新の PyPI リリースを解決します。バージョンを固定しないインストールは、再現性も監査可能性もありません。Windows では 0.1.0 を避けてください。最初のツール呼び出しがハングします（0.2.0 で修正済み）。

**起動時の動作について：**初回起動時には量子 SDK スタックのダウンロードに 1～3 分かかります。 サーバーが応答するまで、起動のたびに約 30 秒かかります。MCP ハンドシェイクの前に SDK がインポートされるためです。 その間に「initialize へのサーバー応答を待機しています」と表示されるのは正常です。

Claude Desktop

設定 → 開発者 → ローカル MCP サーバー → 設定を編集（必ずこのボタンを使用してください。Microsoft Store 版ではファイルが %APPDATA%\Claude ではなく %LOCALAPPDATA%\Packages\Claude_*\... に保存されています）。次に、以下を追加します。

{
  "mcpServers": {
    "nexus": {
      "command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe", // or plain "uvx" on macOS/Linux
      "args": ["qnexus-mcp==0.2.0", "--toolsets", "read,execute"]
    }
  }
}

その後、Claude Desktop を完全に終了して再起動してください。設定が読み込まれるのは完全終了後の起動時のみです。ウィンドウを閉じても以前のプロセスは実行されたままです（トレイアイコン → 終了、または taskkill /F /IM claude.exe）。

VS Code

コマンドパレット → MCP: Open User Configuration（またはワークスペースの .vscode/mcp.json）：

{
  "servers": {
    "nexus": {
      "type": "stdio",
      "command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe", // or plain "uvx" on macOS/Linux
      "args": ["qnexus-mcp==0.2.0", "--toolsets", "read,execute"]
    }
  }
}

Claude Code

claude mcp add nexus -- uvx qnexus-mcp==0.2.0 --toolsets read,execute

その他の MCP クライアント（Cursor、Codex など）

コマンドは同じです。設定の形式は上記 2 種類の JSON 形式のいずれかです（mcpServers または servers + "type": "stdio"）。設定ファイルの保存先については、使用するクライアントのドキュメントをご確認ください。

うまく動作しない場合は、docs/TROUBLESHOOTING.md をご覧ください。実際のクライアント環境で確認されたあらゆる障害モード（設定ファイルのパス違い、初回起動の遅さ、認証、レート制限、Nexus 側で把握されているエラー）を扱っています。

設定

フラグ	環境変数	デフォルト	効果
--toolsets	QNEXUS_MCP_TOOLSETS	read	公開する機能領域（read,execute,manage,destructive）
--allow-spend	QNEXUS_MCP_ALLOW_SPEND	false	クレジットを消費する実行（HQC）を許可
--allow-hardware	QNEXUS_MCP_ALLOW_HARDWARE	false	実 QPU をターゲットとして許可
--allow-destructive	QNEXUS_MCP_ALLOW_DESTRUCTIVE	false	削除／キャンセル／アーカイブを許可
--max-credits	QNEXUS_MCP_MAX_CREDITS	0	呼び出しごとの HQC 上限。0 の場合、すべてのクレジット消費をブロック
--max-outcomes	QNEXUS_MCP_MAX_OUTCOMES	100	結果ごとに返す異なる測定結果の上位 N 件の上限（切り捨ては常に報告されます）
--max-submissions-per-minute	QNEXUS_MCP_MAX_SUBMISSIONS_PER_MINUTE	6	スライディングウィンドウ方式の送信上限。バッチ内の各回路を 1 件としてカウント
--projects	QNEXUS_MCP_PROJECTS	(すべて)	カンマ区切りのプロジェクト許可リスト。変更を伴うすべてのツールで適用

安全性

デフォルトでは読み取り専用です。クレジットを消費する操作やクラウドの状態を変更する操作には、明示的なオプトインフラグとプロトコル内での確認が必要です。また、デフォルトの実行バックエンドは、無料でノイズのないH2-1LEエミュレーターです。送信にはレート制限が適用され、クラウドの変更は直列化されます。破壊的なプロジェクト操作では、対象を完全一致する名前で特定します（部分一致は使用しません）。また、サーバーがNexusトークンを読み取ったり、保存したり、返したりすることはありません。すべての制御はサーバー側で適用されます。MCP ツールのアノテーションはUX上のヒントとしてのみ扱われます。docs/DESIGN.mdの§6〜§7を参照してください。

プロンプトインジェクション（意図的な設計判断）。 Nexusが返す内容はすべて、ジョブ名、プロジェクト名、エラーメッセージ、結果も含め、攻撃者が影響を与えられるコンテンツです（Nexusのユーザーなら誰でもジョブに名前を付けられます）。そのため、信頼できないデータとして扱われます。現在のMCPエコシステムには、「データ」と「指示」を分離する構造的なタグ付けがありません。そのため、ここでは代わりに、インジェクションされたコンテンツが権限を昇格できないことを構造的な境界としています。結果を伴うすべての操作（クレジットの消費、ハードウェアの指定、何かの削除）には、エージェントが設定できない起動フラグに加え、正確な対象とコストを明示したプロトコル内での人間による確認が必要です。インジェクションされたテキストがエージェントの推論を混乱させることはあっても、それだけで何かを消費したり破壊したりすることはできません。この残存リスクは許容され、文書化されており、単なる見落としではありません。

ガバナンス。 これは、メンテナーが1人の初期段階のプロジェクトです（CODEOWNERSを参照）。リリースは、GitHub-OIDC Trusted Publishingを介して1人が公開します（長期間有効なPyPIトークンは使用しません）。この信頼モデルがデプロイ環境で重要な場合は、バージョンを固定してください（上記を参照）。

貢献

CONTRIBUTING.mdを参照してください。貢献はDeveloper Certificate of Originに基づいて受け付けています。コミットには-sを付けて署名してください。

ライセンス

Apache-2.0です。LICENSEおよびNOTICEを参照してください。