Подключение Qwen Code к инструментам через MCP

Qwen Code может подключаться к внешним инструментам и источникам данных через Model Context Protocol (MCP) . MCP-серверы предоставляют Qwen Code доступ к вашим инструментам, базам данных и API.

Возможности MCP

При подключении MCP-серверов вы можете попросить Qwen Code:

• Работать с файлами и репозиториями (чтение/поиск/запись в зависимости от включённых инструментов)
• Выполнять запросы к базам данных (просмотр схемы, запросы, отчёты)
• Интегрировать внутренние сервисы (оборачивать ваши API в виде MCP-инструментов)
• Автоматизировать рабочие процессы (повторяющиеся задачи, доступные как инструменты/промпты)

Быстрый старт

Qwen Code загружает MCP-серверы из раздела mcpServers в вашем settings.json. Настроить серверы можно двумя способами:

• Отредактировав settings.json напрямую
• Используя команды qwen mcp (см. Справочник по CLI)

Добавление первого сервера

1. Добавьте сервер (пример: удалённый HTTP MCP-сервер):

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

2. Откройте диалог управления MCP для просмотра и настройки серверов:

qwen mcp

3. Перезапустите Qwen Code в том же проекте (или запустите его, если он ещё не работал), затем попросите модель использовать инструменты с этого сервера.

Где хранится конфигурация (области видимости)

Большинству пользователей достаточно двух областей видимости:

• Область проекта (по умолчанию): .qwen/settings.json в корне вашего проекта
• Область пользователя: ~/.qwen/settings.json для всех проектов на вашем компьютере

Запись в область пользователя:

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

Настройка серверов

Выбор транспорта

Настройка через settings.json или qwen mcp add

Оба подхода создают одинаковые записи mcpServers в вашем settings.json — используйте тот, который вам удобнее.

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

Безопасность и контроль

Доверие (пропуск подтверждений)

• Доверие к серверу (trust: true): пропускает запросы подтверждения для этого сервера (используйте с осторожностью).

OAuth-аутентификация

Qwen Code поддерживает OAuth 2.0 аутентификацию для MCP-серверов. Это полезно при работе с удалёнными серверами, требующими авторизации.

Базовое использование

При добавлении MCP-сервера с OAuth-учётными данными 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

Важно: настройка Redirect URI

Для OAuth-процесса требуется redirect URI, на который провайдер авторизации отправляет код аутентификации.

• Локальная разработка: По умолчанию Qwen Code использует http://localhost:7777/oauth/callback. Это работает при запуске Qwen Code на локальном компьютере с локальным браузером.

• Удалённые/облачные развёртывания: При запуске Qwen Code на удалённых серверах, в облачных IDE или веб-терминалах редирект на localhost по умолчанию НЕ сработает. Вы ОБЯЗАНЫ настроить --oauth-redirect-uri, указав общедоступный URL, способный принимать OAuth-колбэк.

Пример для удалённых серверов:

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

Вы также можете настроить OAuth, отредактировав settings.json напрямую:

{
  "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
• Обновляются при истечении срока действия (если доступны refresh-токены)
• Проверяются перед каждой попыткой подключения

Используйте команду /mcp auth внутри Qwen Code для интерактивного управления OAuth-аутентификацией.

Фильтрация инструментов (разрешение/запрет инструментов для каждого сервера)

Используйте includeTools / excludeTools для ограничения инструментов, предоставляемых сервером (с точки зрения Qwen Code).

Пример: включение только нескольких инструментов:

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

Глобальные списки разрешений/запретов

Объект mcp в вашем settings.json задаёт глобальные правила для всех MCP-серверов:

• mcp.allowed: список разрешённых имён MCP-серверов (ключи в mcpServers)
• mcp.excluded: список запрещённых имён MCP-серверов

Пример:

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

Устранение неполадок

• Сервер показывает “Disconnected” в qwen mcp list: убедитесь, что URL/команда указаны верно, затем увеличьте timeout.
• Stdio-сервер не запускается: используйте абсолютный путь в command и перепроверьте cwd/env.
• Переменные окружения в JSON не подставляются: убедитесь, что они существуют в окружении, где запущен Qwen Code (окружение оболочки и GUI-приложений может отличаться).

Справочник

Структура settings.json

Конфигурация конкретного сервера (mcpServers)

Добавьте объект mcpServers в ваш файл settings.json:

// ... file contains other config objects
{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

Свойства конфигурации:

Обязательные (одно из следующего):

Опциональные:

Управление MCP-серверами через qwen mcp

Вы всегда можете настроить MCP-серверы, вручную отредактировав settings.json, но 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>