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

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

MCPでできること

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

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

クイックスタート

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

サーバーの設定

トランスポートの選択

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の影響は受けません。長時間実行されるツール呼び出しはスタートアップの問題ではありません。

段階的MCPのロールバック

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

安全性と制御

信頼（確認のスキップ）

• サーバー信頼（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コールバックを受信できる公開アクセス可能なURLを指すように--oauth-redirect-uriを必ず設定する必要があります。

リモートサーバーの例:

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

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...]

--oauth-* フラグは --transport sse および --transport http にのみ適用されます。--transport stdio と組み合わせて使用することはできません。

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

qwen mcp remove <name>