通过 MCP 将 Qwen Code 连接到工具

Qwen Code 可以通过 Model Context Protocol (MCP) 连接到外部工具和数据源。MCP 服务器使 Qwen Code 能够访问你的工具、数据库和 API。

使用 MCP 可以做什么

连接 MCP 服务器后，你可以要求 Qwen Code：

处理文件和仓库（读取/搜索/写入，具体取决于你启用的工具）
查询数据库（检查 schema、执行查询、生成报告）
集成内部服务（将你的 API 封装为 MCP 工具）
自动化工作流（将可重复任务暴露为工具/prompt）

Tip

如果你在寻找“快速上手的一条命令”，请直接跳转到快速开始。

快速开始

Qwen Code 会从 settings.json 中的 mcpServers 字段加载 MCP 服务器。你可以通过以下任一方式配置服务器：

直接编辑 settings.json
使用 qwen mcp 命令（参见 CLI 参考）

添加你的第一个服务器

添加一个服务器（示例：远程 HTTP MCP 服务器）：


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

打开 MCP 管理对话框以查看和管理服务器：


qwen mcp

在同一项目中重启 Qwen Code（如果尚未运行则启动它），然后要求模型使用该服务器中的工具。

配置存储位置（作用域）

大多数用户只需要以下两个作用域：

项目作用域（默认）：项目根目录下的 .qwen/settings.json
用户作用域：你机器上所有项目共享的 ~/.qwen/settings.json

写入用户作用域：


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

Tip

如需了解高级配置层（系统默认值/系统设置及优先级规则），请参阅设置。

配置服务器

选择传输方式

Transport	适用场景	JSON 字段
`http`	推荐用于远程服务；适用于云端 MCP 服务器	`httpUrl`（+ 可选的 `headers`）
`sse`	仅支持 Server-Sent Events 的旧版/已弃用服务器	`url`（+ 可选的 `headers`）
`stdio`	本地进程（脚本、CLI、Docker）	`command`、`args`（+ 可选的 `cwd`、`env`）

Note

如果服务器同时支持两者，请优先选择 HTTP 而非 SSE。

通过 `settings.json` 配置 vs `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

安全与控制

信任（跳过确认）

服务器信任（trust: true）：跳过该服务器的确认提示（请谨慎使用）。

工具过滤（按服务器允许/拒绝工具）

使用 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 服务器名称的拒绝列表

示例：


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

故障排查

qwen mcp list 中服务器显示“Disconnected”：验证 URL/命令是否正确，然后增加 timeout。
Stdio 服务器启动失败：使用绝对 command 路径，并仔细检查 cwd/env。
JSON 中的环境变量未解析：确保它们在 Qwen Code 运行的环境中存在（Shell 环境与 GUI 应用环境可能不同）。

参考

`settings.json` 结构

服务器特定配置（`mcpServers`）

在 settings.json 文件中添加 mcpServers 对象：


// ... 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
    }
  }
}

配置属性：

必填（以下之一）：

Property	描述
`command`	Stdio 传输方式的可执行文件路径
`url`	SSE 端点 URL（例如 `"http://localhost:8080/sse"`）
`httpUrl`	HTTP 流式端点 URL

可选：

Property	类型/默认值	描述
`args`	array	Stdio 传输方式的命令行参数
`headers`	object	使用 `url` 或 `httpUrl` 时的自定义 HTTP 请求头
`env`	object	服务器进程的环境变量。值可以使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量
`cwd`	string	Stdio 传输方式的工作目录
`timeout`	number (default: 600,000)	请求超时时间（毫秒）（默认：600,000ms = 10 分钟）
`trust`	boolean (default: false)	设为 `true` 时，跳过该服务器的所有工具调用确认提示（默认：`false`）
`includeTools`	array	从此 MCP 服务器包含的工具名称列表。指定后，仅此处列出的工具对该服务器可用（白名单行为）。若未指定，默认启用该服务器的所有工具。
`excludeTools`	array	从此 MCP 服务器排除的工具名称列表。列出的工具将不对模型可用，即使服务器已暴露它们。注意：`excludeTools` 优先级高于 `includeTools`——如果工具同时出现在两个列表中，它将被排除。
`targetAudience`	string	你尝试访问的 IAP 保护应用上列入白名单的 OAuth Client ID。与 `authProviderType: 'service_account_impersonation'` 配合使用。
`targetServiceAccount`	string	要模拟的 Google Cloud Service Account 的电子邮件地址。与 `authProviderType: 'service_account_impersonation'` 配合使用。

使用 `qwen mcp` 管理 MCP 服务器

你始终可以通过手动编辑 settings.json 来配置 MCP 服务器，但使用 CLI 通常更快。

添加服务器（`qwen mcp add`）


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

参数/选项	描述	默认值	示例
`<name>`	服务器的唯一名称。	—	`example-server`
`<commandOrUrl>`	要执行的命令（用于 `stdio`）或 URL（用于 `http`/`sse`）。	—	`/usr/bin/python` 或 `http://localhost:8`
`[args...]`	`stdio` 命令的可选参数。	—	`--port 5000`
`-s`, `--scope`	配置作用域（user 或 project）。	`project`	`-s user`
`-t`, `--transport`	传输类型（`stdio`、`sse`、`http`）。	`stdio`	`-t sse`
`-e`, `--env`	设置环境变量。	—	`-e KEY=value`
`-H`, `--header`	为 SSE 和 HTTP 传输设置 HTTP 请求头。	—	`-H "X-Api-Key: abc123"`
`--timeout`	设置连接超时时间（毫秒）。	—	`--timeout 30000`
`--trust`	信任该服务器（跳过所有工具调用确认提示）。	— (`false`)	`--trust`
`--description`	设置服务器的描述。	—	`--description "Local tools"`
`--include-tools`	要包含的工具的逗号分隔列表。	包含所有工具	`--include-tools mytool,othertool`
`--exclude-tools`	要排除的工具的逗号分隔列表。	无	`--exclude-tools mytool`

移除服务器（`qwen mcp remove`）


qwen mcp remove <name>