MCP経由でQwen Codeをツールに接続する

Qwen Codeは、Model Context Protocol (MCP) を通じて外部ツールやデータソースに接続できます。MCPサーバーにより、Qwen Codeはあなたのツール、データベース、APIにアクセスできるようになります。

MCPでできること

MCPサーバーを接続すると、Qwen Codeに以下のことを指示できます:

- ファイルやリポジトリの操作（有効化するツールに応じて、読み取り/検索/書き込み） - データベースのクエリ（スキーマの検査、クエリ実行、レポート作成） - 内部サービスの統合（APIをMCPツールとしてラップ） - ワークフローの自動化（ツールやプロンプトとして公開される反復タスク）

> [!tip] > > 「まず最初のコマンド」を探している場合は、クイックスタートに進んでください。

クイックスタート

Qwen Codeは、settings.jsonのmcpServersからMCPサーバーをロードします。サーバーの設定は以下のいずれかの方法で行えます:

- settings.jsonを直接編集する - qwen mcpコマンドを使用する（CLIリファレンスを参照）

最初のサーバーを追加する

1. サーバーを追加する（例: リモートHTTP MCPサーバー）:

qwen mcp add --transport http my-server http://localhost:3000/mcp

2. Qwen Codeを起動し、MCP管理ダイアログを開いてサーバーを表示・管理します:

qwen

次に、以下を入力します:

/mcp

3. サーバーを追加する前にQwen Codeがすでに起動していた場合は、同じプロジェクトで再起動してください。その後、モデルにそのサーバーのツールを使用するよう指示します。

設定の保存場所（スコープ）

ほとんどのユーザーは、以下の2つのスコープのみで十分です:

- ユーザースコープ（デフォルト）: マシン上のすべてのプロジェクトに適用される ~/.qwen/settings.json - プロジェクトスコープ: プロジェクトルートにある .qwen/settings.json

ユーザースコープに書き込む:

qwen mcp add --scope user --transport http my-server http://localhost:3000/mcp

> [!tip] > > 高度な設定レイヤー（システムデフォルト/システム設定と優先順位ルール）については、設定を参照してください。

サーバーの設定

トランスポートの選択

> [!note] > > サーバーが両方をサポートしている場合は、SSEよりもHTTPを優先してください。

settings.jsonとqwen mcp addによる設定

どちらのアプローチでも、settings.jsonに同じmcpServersエントリが生成されます。好みの方法を使用してください。

Stdioサーバー（ローカルプロセス）

JSON（.qwen/settings.json）:

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

CLI（デフォルトでユーザースコープに書き込み）:

qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING -e API_KEY=$EXTERNAL_API_KEY \
  --timeout 15000 python -m my_mcp_server --port 8080

HTTPサーバー（リモートストリーミングHTTP）

JSON:

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      },
      "timeout": 5000
    }
  }
}

CLI:

qwen mcp add --transport http httpServerWithAuth http://localhost:3000/mcp \
  --header "Authorization: Bearer your-api-token" --timeout 5000

SSEサーバー（リモートServer-Sent Events）

JSON:

{
  "mcpServers": {
    "sseServer": {
      "url": "http://localhost:8080/sse",
      "timeout": 30000
    }
  }
}

CLI:

qwen mcp add --transport sse sseServer http://localhost:8080/sse --timeout 30000

MCPプロンプトとリソースの使用

ツールに加えて、Qwen Codeは他の2つのMCPプリミティブを検出し、利用できるようにします。

プロンプト（スラッシュコマンド）

サーバーがprompts/list経由で公開するプロンプトは、実行可能なスラッシュコマンドになります。検出後、/を入力するとプロンプトが一覧表示されます（MCP: <server>というラベル付き）。他のコマンドと同様に実行できます:

/my_prompt --arg1="value" --arg2="value"
# 位置引数形式も機能します:
/my_prompt "value" "value"
# プロンプトの引数を表示:
/my_prompt help

プロンプトのメッセージはモデルに送信され、モデルがそれに基づいてアクションを実行します。

> 検出は宣言されたpromptsケーパビリティに対して寛容です: 一部のサーバーはprompts/listを実装していますが、initializeケーパビリティからpromptsを省略しています。Qwen Codeはとにかくprompts/listを試行するため、それらのプロンプトも表示されます。プロンプトを本当に持たないサーバーは単にMethod not foundを返しますが、これは無視されます。

リソース

サーバーがresources/list経由で公開するリソースは、サーバーごとに検出されます。/mcpで管理ダイアログを開き、サーバーを選択すると、ツールやプロンプト alongside リソースの数が表示されます。View resourcesを選択してサーバーのリソースURIを閲覧できます。1つを選択すると、説明とMIMEタイプ、およびメッセージに貼り付けるための正確な@server:uri参照が表示されます。プロンプトと同様に、resourcesケーパビリティの宣言は必須ではありません。

@server:uri構文を使用して、メッセージにリソースの内容を挿入します。@、次にサーバー名、コロン、リソースURIの順に入力します:

summarize @myserver:file:///docs/spec.md and list the open questions

@myserver:と入力すると、そのサーバーのリソースのオートコンプリートリストが表示されます。入力を続けると、リソースURIまたはフレンドリ名/タイトルが（大文字小文字を区別せずに）一致するようにフィルタリングされます。URIを暗記する必要はありません。コロンに到達する前にサーバー名の一部を入力するだけで、リソースを公開する一致するサーバーが提案されるため、1つを選択して直接リソースリストに移動できます。送信時、参照されたリソースが読み込まれ、その内容がメッセージに追加されます（テキストはインライン、バイナリブロブは添付ファイルとして）。@server:uri参照はプロンプトに保持されるため、モデルは何を見ているかを認識できます。serverプレフィックスは設定済みのMCPサーバーと一致する必要があります。一致しない場合、トークンは通常のファイルパスとして扱われるため、既存の@path/to/file参照は影響を受けません。信頼されないフォルダではリソースの読み取りは無効になります。

段階的な利用可能性と検出タイムアウト

Qwen Codeは、UIがすでにインタラクティブになった後、バックグラウンドでMCPサーバーを検出します。MCPサーバーの1つが数秒かかる場合（または応答しない場合）でも、数ミリ秒以内にCLIの最初のプロンプトが表示され、モデルのツールリストは各サーバーが検出ハンドシェイクを完了する約1フレーム（〜16ミリ秒）ごとに更新されます。

- インタラクティブモード: UIはすぐに表示され、右下のMCPステータスピルに検出中のN/M MCP servers readyが表示されます。MCPが完了する前にプロンプトを送信した場合、モデルはその時点で準備ができているツールのみを認識します。その後のプロンプトでは、サーバーがオンラインになるにつれてより多くのツールが認識されます。 - 非インタラクティブモード（--prompt、stream-json、ACP）: CLIは最初のプロンプトを送信する前にMCP検出が落ち着くのを待つため、スクリプト/パイプ呼び出しはレガシーな同期動作と同じ完全なツールセットを認識します。

サーバーごとのdiscoveryTimeoutMs

各MCPサーバーには、初期ハンドシェイク（connect + tools/list + prompts/list + resources/list）に許可される時間を制限する、検出専用のタイムアウトが設定されます。デフォルト:

- stdioサーバー: 30秒 - リモートHTTP / SSEサーバー: 5秒（ネットワークリスクが高いため）

必要に応じてサーバーごとにオーバーライドします:

{
  "mcpServers": {
    "slow-stdio": {
      "command": "node",
      "args": ["./slow-server.js"],
      "discoveryTimeoutMs": 60000,
    },
    "flaky-remote": {
      "httpUrl": "https://example.com/mcp",
      "discoveryTimeoutMs": 10000,
    },
  },
}

既存のtimeoutフィールドはツール呼び出しのタイムアウト（各tools/callリクエストに使用され、デフォルトは10分）であり、discoveryTimeoutMsの影響は受けません。長時間実行されるツール呼び出しはスタートアップの問題ではありません。

自動Stdioネゴシエーション

Stdioサーバーはデフォルトでシングルプロセスのレガシー初期化フローを使用します。モダン専用のStdioサーバーに接続するには、自動プロトコルネゴシエーションを有効にします:

{
  "mcpServers": {
    "modern-server": {
      "command": "node",
      "args": ["./server.js"],
      "versionNegotiation": "auto",
    },
  },
}

自動ネゴシエーションは、セッションプロセスを起動する前に設定されたサーバーの短命なコピーを実行し、検出バジェットのうち最大5秒を使用します。非冪等なスタートアップ副作用を持つサーバー、単一オーナーのロックやPIDファイルを持つサーバー、または遅い初期化ハンドシェイクを持つサーバーには、デフォルトのレガシーポリシーを維持してください。

段階的MCPのロールバック

古い同期動作（CLIがUIを表示する前にすべてのMCPサーバーを待つ）が必要な場合は、環境変数にQWEN_CODE_LEGACY_MCP_BLOCKING=1を設定してください。これは少なくとも1リリースの間、エスケープハッチとして保持されます。

安全性と制御

信頼（確認のスキップ）

- サーバー信頼（trust: true）: 信頼されたワークスペース内でのみ、そのサーバーの確認プロンプトをバイパスします（使用は慎重に）。

接続損失時のリプレイ

Qwen Code は、サーバーに trust: true が設定され、ワークスペースが信頼されており、ツールが idempotentHint: true または一貫した読み取り専用の注釈を明示的に宣言している場合にのみ、現在の MCP ツール呼び出しを再接続してリプレイします。読み取り専用の注釈は destructiveHint: true または idempotentHint: false と競合し、リプレイされません。

注釈が欠落している場合、注釈が競合している場合、信頼されていないサーバーの場合、または信頼されていないワークスペースの場合は、接続障害後にリプレイされません。Qwen Code は、サーバーが応答が失われる前に操作を完了していた可能性があるため、結果が不明である可能性があることを報告します。再試行する前に結果を確認してください。この保守的な動作は、注釈のないツールを透過的にリトライしていた以前のリリースとは異なる場合があります。

注釈はサーバーが提供する動作のヒントであり、権限や認可の境界ではありません。自身が制御し、注釈を検証したサーバーに対してのみ trust: true を設定してください。

OAuth認証

Qwen CodeはMCPサーバーのOAuth 2.0認証をサポートしています。これは、認証を必要とするリモートサーバーにアクセスする場合に便利です。

基本的な使い方

OAuth認証情報を使用してMCPサーバーを追加すると、Qwen Codeが認証フローを自動的に処理します:

qwen mcp add --transport sse oauth-server https://api.example.com/sse/ \
  --oauth-client-id your-client-id \
  --oauth-redirect-uri https://your-server.com/oauth/callback \
  --oauth-authorization-url https://provider.example.com/authorize \
  --oauth-token-url https://provider.example.com/token

重要: リダイレクトURIの設定

OAuthフローには、認証プロバイダーが認証コードを送信するリダイレクトURIが必要です。

- ローカル開発: デフォルトでは、Qwen Codeはhttp://localhost:7777/oauth/callbackを使用します。これは、ローカルマシンでローカルブラウザを使用してQwen Codeを実行している場合に機能します。

- リモート/クラウドデプロイ: リモートサーバー、クラウドIDE、またはWebターミナルでQwen Codeを実行する場合、デフォルトのlocalhostリダイレクトは機能しません。--oauth-redirect-uri に /oauth/callback で終わる公開 URL を設定し、そのパスを Qwen Code が動作しているマシンの http://127.0.0.1:7777/oauth/callback にリバースプロキシしてください。Qwen Code は TLS を終端しません。プロキシが TLS を終端する必要があります。

リモートサーバーの例:

qwen mcp add --transport sse remote-server https://api.example.com/sse/ \
  --oauth-redirect-uri https://your-remote-server.example.com/oauth/callback

例えば、リバースプロキシでこのコールバックパスのみをローカルリスナーに転送できます。

location = /oauth/callback {
  proxy_pass http://127.0.0.1:7777;
}

settings.jsonによる手動設定

settings.jsonを直接編集してOAuthを設定することもできます:

{
  "mcpServers": {
    "oauthServer": {
      "url": "https://api.example.com/sse/",
      "oauth": {
        "enabled": true,
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "authorizationUrl": "https://provider.example.com/authorize",
        "tokenUrl": "https://provider.example.com/token",
        "redirectUri": "https://your-server.com/oauth/callback",
        "scopes": ["read", "write"]
      }
    }
  }
}

OAuth設定プロパティ:

トークン管理

OAuthトークンは自動的に以下のように処理されます:

- 保存: デフォルトでは~/.qwen/mcp-oauth-tokens.json（プレーンテキスト、モード0600）に保存されます。QWEN_CODE_FORCE_ENCRYPTED_FILE_STORAGE=trueが設定されている場合、Qwen Codeは利用可能な場合はキーチェーンバックのストレージを使用するか、AES-256-GCMで暗号化された~/.qwen/mcp-oauth-tokens-v2.jsonを使用します。 - 更新: 期限切れになった場合（リフレッシュトークンが利用可能な場合） - 検証: 各接続試行の前

> [!WARNING] > デフォルトでは、OAuthトークンは暗号化されずにディスクに保存されます。共有マシンまたはマルチユーザーマシンでは、QWEN_CODE_FORCE_ENCRYPTED_FILE_STORAGE=trueを設定して認証情報を保護してください。

Qwen Code内の/mcpダイアログを使用して、MCPサーバーを検査し、認証を対話的に管理します。

ツールのフィルタリング（サーバーごとのツールの許可/拒否）

includeTools / excludeToolsを使用して、サーバーによって公開されるツールを（Qwen Codeの観点から）制限します。

例: いくつかのツールのみを含める:

{
  "mcpServers": {
    "filteredServer": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "includeTools": ["safe_tool", "file_reader", "data_processor"],
      "timeout": 30000
    }
  }
}

グローバル許可/拒否リスト

settings.jsonのmcpオブジェクトは、すべてのMCPサーバーに対するグローバルルールを定義します:

- mcp.allowed: MCPサーバー名（mcpServersのキー）の許可リスト - mcp.excluded: MCPサーバー名の拒否リスト

どちらのリストもグロブパターンをサポートしています。*は任意の文字列に、?は1文字にマッチします（例: "*puppeteer*"は名前がpuppeteerを含むすべてのサーバーにマッチ）。グロブ文字を含まないエントリは完全に一致します。サーバーが両方のリストにマッチする場合、mcp.excludedが優先されます。

例:

{
  "mcp": {
    "allowed": ["my-trusted-server", "*-internal"],
    "excluded": ["experimental-server"]
  }
}

トラブルシューティング

- qwen mcp listでサーバーが「Disconnected」と表示される: URL/コマンドが正しいことを確認し、timeoutを増やしてください。 - Stdioサーバーが起動しない: 絶対パスのcommandを使用し、cwd/envを再確認してください。 - JSON内の環境変数が解決されない: Qwen Codeが実行されている環境（シェルとGUIアプリの環境は異なる場合があります）にそれらが存在することを確認してください。

リファレンス

settings.jsonの構造

サーバー固有の設定（mcpServers）

settings.jsonファイルにmcpServersオブジェクトを追加します:

// ... ファイルには他の設定オブジェクトが含まれます
{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

設定プロパティ:

必須（以下のいずれか）:

オプション:

qwen mcpによるMCPサーバーの管理

settings.jsonを手動で編集してMCPサーバーを設定することもできますが、CLIを使用する方が通常は高速です。

サーバーの追加（qwen mcp add）

qwen mcp add [options] <name> <commandOrUrl> [args...]

サーバーの削除 (qwen mcp remove)

qwen mcp remove <name>