Qiskit Documentation MCP Server

qiskit-docs-mcp-server

Qiskit のドキュメント、ガイド、API リファレンスを検索・取得するための MCP サーバーです。

概要

Qiskit Documentation MCP Server を使用すると、AI アシスタントやエージェントが Qiskit のドキュメントエコシステム全体にシームレスにアクセスできます。標準化された Model Context Protocol インターフェースを通じて、SDK モジュールのドキュメント、実装ガイド、ベストプラクティスをインテリジェントに取得できます。

主な機能

• 📚 ドキュメント全体へのアクセス：すべての Qiskit SDK モジュール、アドオンパッケージ、API リファレンス、ガイド、チュートリアルを検索できます
• 🔄 動的なコンテンツ検出：公開中のサイトマップから利用可能なドキュメントを自動的に検出します。新しいコンテンツが公開されても手動で更新する必要はありません
• 📖 実装ガイド：最適化、エラー緩和、動的回路などのベストプラクティスにアクセスできます
• 🔍 スマート検索：ファジーマッチングで Qiskit ドキュメント全体を検索できます
• 🎯 認証不要：API トークンなしで公開ドキュメントにアクセスできます
• 📝 Markdown 出力：AI がすぐに利用できる、整形済みのドキュメントを出力します
• ⚡ 高速な取得：TTL キャッシュと設定可能なタイムアウトを備えた、効率的な HTTP ベースのドキュメント取得を実現します

コンポーネント

ツール

サーバーはドキュメントにアクセスするための 3 つのツールを実装しています。

ツール	説明	パラメーター
search_docs_tool	Qiskit ドキュメントを検索します。デフォルトではクエリに関連する短いスニペットを返すため、エージェントが繰り返し使用しても応答が簡潔に保たれます	query：検索クエリ文字列 scope：検索範囲のフィルター — all（デフォルト）、documentation、api、learning、tutorials top_k：返す結果の最大数（デフォルト：5、上限：10） detail：snippet（デフォルト。結果ごとの短い抜粋）または full（ページ本文全体。単一ページには get_page_tool の使用を推奨）
get_page_tool	任意の Qiskit ドキュメントページを取得し、Markdown として返します	url：完全な URL または相対パス（例：guides/transpile、api/qiskit/circuit） max_length：返す文字数の最大値（デフォルト：20000、0 で無制限） offset：ページネーション用の文字オフセット（デフォルト：0）
lookup_error_code_tool	Qiskit／IBM Quantum のエラーコードを検索します	code：4 桁のエラーコード（例：1002、7001、8004）

リソース

サーバーは、利用可能なドキュメントを一覧表示する 6 つのリソースを提供します。モジュール、アドオン、ガイド、チュートリアル、API パッケージのコンテンツ一覧は、ドキュメントのサイトマップから動的に検出されてキャッシュされます。サイトマップにアクセスできない場合は、ハードコードされた代替値が使用されます。

リソース URI	説明
qiskit-docs://modules	URL パス付きの、すべての Qiskit SDK モジュールの一覧
qiskit-docs://addons	URL パス付きの、Qiskit アドオンパッケージの一覧
qiskit-docs://guides	実装ガイドとベストプラクティスの一覧
qiskit-docs://tutorials	URL パス付きの、Qiskit チュートリアルの一覧
qiskit-docs://api-packages	API パッケージ（runtime、transpiler、REST APIs など）の一覧
qiskit-docs://error-codes	Qiskit エラーコードのカテゴリ一覧

リソーステンプレート

リソース URI	説明
qiskit-docs://modules/{module_name}	特定の SDK モジュールのドキュメント
qiskit-docs://guides/{guide_name}	特定の実装ガイド
qiskit-docs://addons/{addon_name}	特定のアドオンパッケージのドキュメント

前提条件

• Python 3.10 以降
• uv パッケージマネージャー（推奨）
• IBM Quantum Documentation にアクセスできるインターネット接続

インストール

PyPI からインストール

最も簡単なインストール方法は、pip を使うことです。

pip install qiskit-docs-mcp-server

または、uvx を使います（推奨）。

uvx qiskit-docs-mcp-server

ソースからインストール

このプロジェクトでは、仮想環境と依存関係の管理に uv を使用します。uv がインストールされていない場合は、https://docs.astral.sh/uv/getting-started/installation/ の手順を確認してください。

uv でプロジェクトをセットアップする

1. リポジトリをクローンします：

   git clone https://github.com/Qiskit/mcp-servers.git
   cd mcp-servers/qiskit-docs-mcp-server
   

2. プロジェクトを初期化または同期します：

   # This will create a virtual environment and install dependencies
   uv sync
   

設定

環境変数

サーバーは環境変数を使って設定できます。

変数	説明	デフォルト
QISKIT_DOCS_BASE	Qiskit ドキュメントのベース URL	https://quantum.cloud.ibm.com/docs/
QISKIT_HTTP_TIMEOUT	HTTP リクエストのタイムアウト（秒）	10.0
QISKIT_DOCS_CACHE_TTL	ページキャッシュの TTL（秒）	3600.0
QISKIT_SEARCH_CACHE_TTL	検索／JSON キャッシュの TTL（秒）	300.0
QISKIT_SEARCH_BASE_URL	検索 API のベース URL	https://quantum.cloud.ibm.com/

オプションの設定

プロジェクトディレクトリに .env ファイルを作成します。

# Optional: Customize documentation URLs
QISKIT_DOCS_BASE=https://quantum.cloud.ibm.com/docs/
QISKIT_HTTP_TIMEOUT=15.0
QISKIT_DOCS_CACHE_TTL=3600.0
QISKIT_SEARCH_CACHE_TTL=300.0

クイックスタート

サーバーの実行

uv run qiskit-docs-mcp-server

サーバーが起動し、MCP 接続を待ち受けます。

MCP クライアントでの使用

Claude Desktop の設定

Claude Desktop の設定ファイルに追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "qiskit-docs": {
      "command": "uvx",
      "args": ["qiskit-docs-mcp-server"]
    }
  }
}

Cline の設定

Cline の MCP 設定に追加します。

{
  "mcpServers": {
    "qiskit-docs": {
      "command": "uvx",
      "args": ["qiskit-docs-mcp-server"]
    }
  }
}

LangChain 統合の例

注記： LangChain の例を実行するには、依存関係をインストールする必要があります。

pip install langchain-mcp-adapters langchain-openai langgraph

import asyncio

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

async def main():
    # Configure MCP client
    async with MultiServerMCPClient(
        {
            "qiskit-docs": {
                "command": "qiskit-docs-mcp-server",
                "args": [],
                "transport": "stdio",
            }
        }
    ) as client:
        # Create agent with LLM and MCP tools
        agent = create_react_agent(
            ChatOpenAI(model="gpt-4o"),
            client.get_tools(),
        )

        # Query documentation
        response = await agent.ainvoke(
            {"messages": [("user", "How do I create a quantum circuit in Qiskit?")]}
        )
        print(response["messages"][-1].content)

asyncio.run(main())

使用例

ドキュメントを検索する

# Search returns short snippets (not full pages) — cheap to call inside an agent
result = await search_docs_tool("transpiler optimization")
print(f"Showing {result['returned_results']} of {result['total_results']} matches")
for item in result["results"]:
    print(f"- {item['title']}: {item['url']}")
    print(f"    {item['snippet']}")

# Then fetch the full content of the one page you want
page = await get_page_tool(result["results"][0]["url"])
print(page["documentation"])

注記（動作の変更）： search_docs_tool は、デフォルトでクエリに関連する短い スニペットを返し、結果数を top_k（デフォルトは 5）に制限するようになりました。デフォルトの （detail="snippet"）モードでは、各結果には全文の text 本文ではなく snippet フィールドが含まれ、 id, url, title, pageTitle, module, section, snippet のみに制限されます。以前の動作に戻すには、 detail="full" を指定します。この指定により、各結果の全文の text 本文とすべての上流フィールドが復元され、 デフォルトではすべての一致結果が返されます（top_k による上限はありません）。明示的に top_k を指定した場合は、full モードでも件数が制限されますが、snippet モードの上限には 制限されません。1 ページの全文を取得する場合は、get_page_tool を使用してください。 total_results は一致結果の総数、returned_results は実際に返された件数です（full モードでは、明示的に top_k を設定しない限り、total_results と同じです）。

ドキュメントページを取得する

# Fetch circuit module API reference
result = await get_page_tool("api/qiskit/circuit")
print(result["documentation"])

# Fetch with pagination for large pages
result = await get_page_tool("api/qiskit/circuit", max_length=5000)
if result["has_more"]:
    next_page = await get_page_tool("api/qiskit/circuit", offset=result["next_offset"])

エラーコードを調べる

# Look up error code 1002
result = await lookup_error_code_tool("1002")
print(result["details"])

利用可能なドキュメント

SDK モジュール

モジュール	説明
circuit	量子回路の構築と操作
quantum_info	量子情報理論のユーティリティ
transpiler	回路のトランスパイルと最適化
synthesis	回路合成アルゴリズム
dagcircuit	量子回路の DAG 表現
passmanager	トランスパイラーパスマネージャーのフレームワーク
converters	回路形式の変換機能
compiler	高水準のコンパイルルーチン
primitives	Sampler と Estimator のプリミティブ
providers	バックエンドプロバイダーとジョブ管理
result	ジョブ結果の処理と分析
visualization	回路と結果の可視化
qasm2	OpenQASM 2.0 のサポート
qasm3	OpenQASM 3.0 のサポート
qpy	Qiskit の Python シリアライゼーション形式
utils	汎用ユーティリティ関数
exceptions	Qiskit の例外クラス

実装ガイド

ガイド	説明
quick-start	Qiskit を使い始める
construct-circuits	量子回路を構築、操作する
transpile	対象バックエンド向けに回路をトランスパイルする
transpiler-stages	トランスパイラーのパイプラインステージを理解する
configure-error-mitigation	プリミティブのエラー緩和を設定する
configure-error-suppression	エラー抑制の手法を設定する
primitives	Sampler および Estimator プリミティブを使用する
execution-modes	ジョブ、セッション、バッチの実行モード
dynamic-circuits	回路途中の測定と古典制御
functions	Qiskit Functions の概要

利用可能な 30 以上のガイドの完全な一覧については、qiskit-docs://guides リソースを参照してください。

機能

ページネーションのサポート

大きなドキュメントページは自動的にページ分割されます。max_length と offset を使用して、取得するコンテンツを制御します。

# Fetch first 5000 characters
result = await get_page_tool("api/qiskit/circuit", max_length=5000)
# result["has_more"] == True, result["next_offset"] == 5000

# Fetch unlimited content
result = await get_page_tool("api/qiskit/circuit", max_length=0)

メタデータの付加

すべてのレスポンスには詳細なメタデータが含まれます。

{
    "status": "success",
    "url": "https://quantum.cloud.ibm.com/docs/api/qiskit/circuit",
    "documentation": "...",
    "has_more": False,
    "total_length": 15420,
    "metadata": {
        "url": "https://quantum.cloud.ibm.com/docs/api/qiskit/circuit",
        "timestamp": "2026-03-03T03:00:00Z",
        "content_type": "markdown",
        "content_length": 15420
    }
}

サイトマップの動的検出

リソース一覧（モジュール、アドオン、ガイド、チュートリアル、API パッケージ）は、起動時にライブドキュメントサイトマップから自動的に検出されます。これにより、コードを変更しなくても、サーバーが新しいコンテンツに対応できます。サイトマップにアクセスできない場合、サーバーは constants.py にハードコードされた値にフォールバックします。

ライブサイトマップからハードコードされたフォールバック値を更新するには、次を実行します。

cd qiskit-docs-mcp-server
uv run python scripts/update_fallback_constants.py

これにより、更新された定数の一覧が出力され、constants.py にコピーできます。

HTML から Markdown への変換

ドキュメントは自動的に HTML から、AI での利用と人間の読みやすさに最適化された、すっきりした Markdown 形式に変換されます。

開発

プロジェクト構成

src/qiskit_docs_mcp_server/
├── server.py           # MCP server definition (tools, resources, prompts)
├── data_fetcher.py     # Business logic for fetching and processing documentation
├── http.py             # HTTP infrastructure: client management, caching, retries
├── sitemap.py          # Dynamic sitemap discovery and page classification
├── html_processing.py  # HTML content extraction and markdown conversion
└── constants.py        # Configuration constants and hardcoded fallback values

scripts/
└── update_fallback_constants.py  # Regenerate fallback values from live sitemap

テストの実行

# Run all tests
./run_tests.sh

# Or use pytest directly
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=src --cov-report=html

コード品質

# Format code
uv run ruff format src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type check
uv run mypy src/

例

動作する完全な例については、examples/ ディレクトリを参照してください。

• langchain_agent.py - 複数の LLM プロバイダーを使用する LangChain エージェント
• langchain_agent.ipynb - 対話型の Jupyter ノートブックチュートリアル
• README.md - 詳細な例のドキュメント

トラブルシューティング

接続の問題

問題：「ドキュメントの取得に失敗しました」 解決策：インターネット接続を確認し、https://quantum.cloud.ibm.com/docs/ にアクセスできることを確認してください。

タイムアウトエラー

問題：「リクエストがタイムアウトしました」 解決策：タイムアウト値を増やします。

export QISKIT_HTTP_TIMEOUT=30.0

ページが見つからない

問題：get_page_tool から「取得に失敗しました」というエラーが返される 解決策：search_docs_tool を使用して正しい URL を検索するか、有効なパスについて qiskit-docs://modules および qiskit-docs://guides リソースを確認してください。

貢献

貢献を歓迎します。ガイドラインについては、リポジトリのルートにある CONTRIBUTING.md ファイルを参照してください。

ライセンス

このプロジェクトは Apache License 2.0 のもとでライセンスされています。詳細については LICENSE ファイルを参照してください。

リンク

• Qiskit ドキュメント
• Model Context Protocol
• MCP Registry
• GitHub リポジトリ

サポート

問題や質問については、以下をご利用ください。

• GitHub の問題
• Qiskit Slack