Skip to Content
工具MCP 服务器

使用 Qwen Code 的 MCP 服务器

本文档提供了配置和使用 Model Context Protocol (MCP) 服务器与 Qwen Code 配合的指南。

什么是 MCP server？

MCP server 是一个通过 Model Context Protocol 向 CLI 暴露工具和资源的应用程序，使其能够与外部系统和数据源进行交互。MCP server 充当了模型与你的本地环境或其他服务（如 API）之间的桥梁。

MCP server 使 CLI 能够：

  • 发现工具： 通过标准化的 schema 定义列出可用工具、它们的描述和参数。
  • 执行工具： 使用定义好的参数调用特定工具并接收结构化响应。
  • 访问资源： 从特定资源读取数据（尽管 CLI 主要专注于工具执行）。

通过 MCP server，你可以扩展 CLI 的功能，使其执行超出内置特性之外的操作，例如与数据库、API、自定义脚本或专业工作流进行交互。

核心集成架构

Qwen Code 通过核心包（packages/core/src/tools/）中内置的一套复杂的发现与执行系统，与 MCP 服务器进行集成：

发现阶段（mcp-client.ts）

发现过程由 discoverMcpTools() 函数编排，该函数会：

  1. 遍历配置的服务器：从你的 settings.json 中的 mcpServers 配置读取服务器列表
  2. 建立连接：使用合适的传输机制（Stdio、SSE 或 Streamable HTTP）连接到各服务器
  3. 获取工具定义：通过 MCP 协议从每个服务器拉取工具定义信息
  4. 清理并验证 schema：确保工具的 schema 兼容 Qwen API
  5. 注册工具：将工具注册进全局工具注册表，并处理可能的命名冲突问题

执行层 (mcp-tool.ts)

每个发现的 MCP 工具都会被封装在一个 DiscoveredMCPTool 实例中，该实例：

  • 处理确认逻辑：根据服务器信任设置和用户偏好进行判断
  • 管理工具执行：通过正确的参数调用 MCP 服务器
  • 处理响应：为 LLM 上下文和用户展示分别处理返回结果
  • 维护连接状态：处理超时等连接问题

传输机制

CLI 支持三种 MCP 传输类型：

  • Stdio Transport：启动一个子进程并通过 stdin/stdout 进行通信
  • SSE Transport：连接到 Server-Sent Events 端点
  • Streamable HTTP Transport：使用 HTTP 流进行通信

如何设置你的 MCP 服务器

Qwen Code 使用 settings.json 文件中的 mcpServers 配置来定位并连接 MCP 服务器。该配置支持多个服务器，并可使用不同的传输机制。

在 settings.json 中配置 MCP 服务器

你可以在 settings.json 文件中通过两种主要方式配置 MCP 服务器：通过顶层的 mcpServers 对象来定义特定的服务器配置，以及通过 mcp 对象来配置控制服务器发现和执行的全局设置。

全局 MCP 设置 (mcp)

settings.json 中的 mcp 对象允许你为所有 MCP 服务器定义全局规则。

  • mcp.serverCommand (string)：用于启动 MCP 服务器的全局命令。
  • mcp.allowed (字符串数组)：允许连接的 MCP 服务器名称列表。如果设置了此项，将只连接此列表中的服务器（与 mcpServers 对象中的键匹配）。
  • mcp.excluded (字符串数组)：要排除的 MCP 服务器名称列表。此列表中的服务器将不会被连接。

示例：

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

服务器特定配置 (mcpServers)

mcpServers 对象用于定义 CLI 需要连接的每个 MCP 服务器。

配置结构

在你的 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
    }
  }
}

配置属性

每个服务器配置支持以下属性：

必需（以下之一）

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

可选参数

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

远程 MCP 服务器的 OAuth 支持

Qwen Code 支持通过 SSE 或 HTTP 传输方式对远程 MCP 服务器进行 OAuth 2.0 认证。这使得你可以安全地访问需要认证的 MCP 服务器。

自动 OAuth 发现

对于支持 OAuth 发现的服务器，你可以省略 OAuth 配置，让 CLI 自动发现：

{
  "mcpServers": {
    "discoveredServer": {
      "url": "https://api.example.com/sse"
    }
  }
}

CLI 将自动：

  • 检测服务器何时需要 OAuth 认证（401 响应）
  • 从服务器元数据中发现 OAuth 端点
  • 如果支持，执行动态客户端注册
  • 处理 OAuth 流程和 token 管理

认证流程

当连接到启用 OAuth 的服务器时：

  1. 初始连接尝试 失败，返回 401 Unauthorized
  2. OAuth 发现 找到授权和令牌端点
  3. 浏览器打开 进行用户认证（需要本地浏览器访问权限）
  4. 授权码 被交换为访问令牌
  5. 令牌被安全存储 以供将来使用
  6. 连接重试 使用有效令牌成功连接

浏览器重定向要求

重要提示： OAuth 认证要求你的本地机器能够：

  • 打开网页浏览器进行认证
  • 在 http://localhost:7777/oauth/callback 接收重定向

此功能在以下环境中无法工作：

  • 没有浏览器访问权限的无头环境
  • 没有 X11 转发的远程 SSH 会话
  • 不支持浏览器的容器化环境

管理 OAuth 认证

使用 /mcp auth 命令来管理 OAuth 认证：

 
# 列出需要认证的服务器
/mcp auth
# 与特定服务器进行身份验证
/mcp auth serverName
 
# 如果 token 过期则重新认证
/mcp auth serverName

OAuth 配置属性

  • enabled (boolean): 为此服务器启用 OAuth
  • clientId (string): OAuth 客户端标识符（使用动态注册时可选）
  • clientSecret (string): OAuth 客户端密钥（公共客户端可选）
  • authorizationUrl (string): OAuth 授权端点（省略时自动发现）
  • tokenUrl (string): OAuth token 端点（省略时自动发现）
  • scopes (string[]): 必需的 OAuth scopes
  • redirectUri (string): 自定义重定向 URI（默认为 http://localhost:7777/oauth/callback）
  • tokenParamName (string): SSE URLs 中 token 的查询参数名称
  • audiences (string[]): token 有效的受众列表

#### Token 管理

OAuth tokens 会自动：

- **安全存储** 在 `~/.qwen/mcp-oauth-tokens.json`
- **自动刷新** 当 token 过期时（如果有 refresh token）
- **连接前验证** 每次连接尝试前
- **清理无效或过期 token**

#### 认证提供者类型

你可以使用 `authProviderType` 属性来指定认证提供者类型：

- **`authProviderType`** (string)：指定认证提供者。可以是以下值之一：
  - **`dynamic_discovery`**（默认）：CLI 将自动从服务器发现 OAuth 配置。
  - **`google_credentials`**：CLI 将使用 Google Application Default Credentials (ADC) 来与服务器进行认证。使用此提供者时，你必须指定所需的 scopes。
  - **`service_account_impersonation`**：CLI 将模拟一个 Google Cloud Service Account 来与服务器进行认证。这对于访问受 IAP 保护的服务非常有用（这是专门为 Cloud Run 服务设计的）。

#### Google Credentials

```json
{
  "mcpServers": {
    "googleCloudServer": {
      "httpUrl": "https://my-gcp-service.run.app/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": ["https://www.googleapis.com/auth/userinfo.email"]
      }
    }
  }
}

Service Account Impersonation

要使用 Service Account Impersonation 进行身份验证，你需要将 authProviderType 设置为 service_account_impersonation，并提供以下属性：

  • targetAudience (string)：在你尝试访问的受 IAP 保护的应用程序上允许列出的 OAuth Client ID。
  • targetServiceAccount (string)：要模拟的 Google Cloud Service Account 的邮箱地址。

CLI 将使用你本地的 Application Default Credentials (ADC) 为指定的服务账户和受众生成一个 OIDC ID token。然后这个 token 将用于与 MCP server 进行身份验证。

设置说明

  1. 创建  或使用现有的 OAuth 2.0 客户端 ID。 要使用现有的 OAuth 2.0 客户端 ID，请按照 如何共享 OAuth 客户端  中的步骤操作。
  2. 将 OAuth ID 添加到应用程序的 程序化访问  白名单中。 由于 Cloud Run 尚未在 gcloud iap 中作为受支持的资源类型，你必须在项目级别将客户端 ID 加入白名单。
  3. 创建一个 service account。 文档 ，Cloud Console 链接 
  4. 将 service account 和用户添加到 IAP 策略中，可以在 Cloud Run 服务本身的“安全”标签页中操作，或通过 gcloud 命令行工具完成。
  5. 为所有需要访问 MCP Server 的用户和组 授予 模拟 service account  所需的权限（即 roles/iam.serviceAccountTokenCreator）。
  6. 为你的项目 启用  IAM Credentials API。

示例配置

Python MCP Server (Stdio)

{
  "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
    }
  }
}

Node.js MCP Server (Stdio)

{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["dist/server.js", "--verbose"],
      "cwd": "./mcp-servers/node",
      "trust": true
    }
  }
}

基于 Docker 的 MCP Server

{
  "mcpServers": {
    "dockerizedServer": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY",
        "-v",
        "${PWD}:/workspace",
        "my-mcp-server:latest"
      ],
      "env": {
        "API_KEY": "$EXTERNAL_SERVICE_TOKEN"
      }
    }
  }
}

基于 HTTP 的 MCP Server

{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "timeout": 5000
    }
  }
}

带自定义 headers 的基于 HTTP 的 MCP Server

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token",
        "X-Custom-Header": "custom-value",
        "Content-Type": "application/json"
      },
      "timeout": 5000
    }
  }
}

带工具过滤的 MCP Server

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

带 Service Account 模拟的 SSE MCP Server

{
  "mcpServers": {
    "myIapProtectedServer": {
      "url": "https://my-iap-service.run.app/sse",
      "authProviderType": "service_account_impersonation",
      "targetAudience": "YOUR_IAP_CLIENT_ID.apps.googleusercontent.com",
      "targetServiceAccount": "your-sa@your-project.iam.gserviceaccount.com"
    }
  }
}

Discovery 过程详解

当 Qwen Code 启动时，它会通过以下详细流程执行 MCP server 的 discovery：

1. 服务器迭代与连接

对于 mcpServers 中配置的每个 server：

  1. 状态跟踪开始： Server 状态设置为 CONNECTING
  2. 传输层选择： 根据配置属性选择：
    • httpUrl → StreamableHTTPClientTransport
    • url → SSEClientTransport
    • command → StdioClientTransport
  3. 建立连接： MCP client 尝试在配置的超时时间内建立连接
  4. 错误处理： 连接失败会被记录日志，并将 server 状态设置为 DISCONNECTED

2. 工具发现

连接成功后：

  1. 工具列表获取： 客户端调用 MCP 服务器的工具列表 endpoint
  2. Schema 验证： 对每个工具的 function 声明进行验证
  3. 工具过滤： 根据 includeTools 和 excludeTools 配置对工具进行过滤
  4. 名称清理： 工具名称会被清理以满足 Qwen API 要求：
    • 无效字符（非字母数字、下划线、点、连字符）会被替换为下划线
    • 超过 63 个字符的名称会在中间被截断并替换为 (___)

3. 冲突解决

当多个服务器暴露了同名工具时：

  1. 首次注册优先： 第一个注册该工具名称的服务器将获得无前缀的名称
  2. 自动添加前缀： 后续服务器的工具名称会被加上前缀：serverName__toolName
  3. 注册表跟踪： 工具注册表会维护服务器名称与其工具之间的映射关系

4. Schema 处理

工具参数 schema 会经过清理以确保 API 兼容性：

  • $schema 属性 会被移除
  • additionalProperties 会被剥离
  • 包含 default 的 anyOf 会移除默认值（为了兼容 Vertex AI）
  • 递归处理 会应用到嵌套的 schema

5. 连接管理

在发现阶段之后：

  • 持久连接： 成功注册工具的服务器会保持连接
  • 清理： 没有提供可用工具的服务器连接会被关闭
  • 状态更新： 最终服务器状态会被设置为 CONNECTED 或 DISCONNECTED

工具执行流程

当模型决定使用某个 MCP 工具时，会按照以下流程执行：

1. 工具调用

模型会生成一个 FunctionCall，包含：

  • 工具名称： 注册时的名称（可能带有前缀）
  • 参数： 符合工具参数 schema 的 JSON 对象

2. 确认流程

每个 DiscoveredMCPTool 都实现了复杂的确认逻辑：

基于信任的跳过机制

if (this.trust) {
  return false; // 无需确认
}

动态白名单管理

系统维护以下内部白名单：

  • 服务器级别： serverName → 来自此服务器的所有工具都被信任
  • 工具级别： serverName.toolName → 此特定工具被信任

用户选择处理

当需要确认时，用户可以选择：

  • 仅本次执行： 只执行这一次
  • 始终允许此工具： 添加到工具级别的白名单
  • 始终允许此服务器： 添加到服务器级别的白名单
  • 取消： 中止执行

3. 执行

确认后（或绕过信任提示后）：

  1. 参数准备： 参数会根据工具的 schema 进行验证

  2. MCP 调用： 底层 CallableTool 会向服务器发起调用：

    const functionCalls = [
  {
    name: this.serverToolName, // 原始服务器工具名称
    args: params,
  },
];

  3. 响应处理： 结果会被格式化，分别用于 LLM 上下文和用户展示

4. 响应处理

执行结果包含：

  • llmContent： 供语言模型使用的原始响应内容
  • returnDisplay： 用于用户展示的格式化输出（通常是 markdown 代码块中的 JSON）

如何与你的 MCP 服务器交互

使用 /mcp 命令

/mcp 命令提供关于你的 MCP 服务器配置的完整信息：

/mcp

该命令会显示以下内容：

  • 服务器列表： 所有已配置的 MCP 服务器
  • 连接状态： CONNECTED、CONNECTING 或 DISCONNECTED
  • 服务器详情： 配置摘要（不包含敏感数据）
  • 可用工具： 每个服务器提供的工具列表及其描述
  • 发现状态： 整体 discovery 过程的状态

示例 /mcp 输出

MCP Servers Status:

📡 pythonTools (CONNECTED)
  Command: python -m my_mcp_server --port 8080
  Working Directory: ./mcp-servers/python
  Timeout: 15000ms
  Tools: calculate_sum, file_analyzer, data_processor

🔌 nodeServer (DISCONNECTED)
  Command: node dist/server.js --verbose
  Error: Connection refused

🐳 dockerizedServer (CONNECTED)
  Command: docker run -i --rm -e API_KEY my-mcp-server:latest
  Tools: docker__deploy, docker__status

Discovery State: COMPLETED

工具使用

一旦被发现，MCP 工具就会像内置工具一样提供给 Qwen 模型使用。模型将自动：

  1. 根据你的请求选择合适的工具
  2. 显示确认对话框（除非服务器是受信任的）
  3. 使用正确的参数执行工具
  4. 以用户友好的格式显示结果

状态监控和故障排除

连接状态

MCP 集成会跟踪几种状态：

服务器状态 (MCPServerStatus)

  • DISCONNECTED: 服务器未连接或出现错误
  • CONNECTING: 正在尝试连接
  • CONNECTED: 服务器已连接并准备就绪

发现阶段 (MCPDiscoveryState)

  • NOT_STARTED: 尚未开始发现
  • IN_PROGRESS: 正在发现服务器
  • COMPLETED: 发现完成（无论是否有错误）

常见问题和解决方案

服务器无法连接

症状： 服务器显示 DISCONNECTED 状态

排查步骤：

  1. 检查配置： 确认 command、args 和 cwd 配置正确
  2. 手动测试： 直接运行服务器命令，确保可以正常工作
  3. 检查依赖： 确保所有必需的 packages 都已安装
  4. 查看日志： 检查 CLI 输出中的错误信息
  5. 验证权限： 确保 CLI 可以执行服务器命令

未发现工具

症状： 服务器连接成功但没有可用工具

排查步骤：

  1. 验证工具注册： 确保你的服务器实际注册了工具
  2. 检查 MCP 协议： 确认你的服务器正确实现了 MCP 工具列表功能
  3. 查看服务器日志： 检查 stderr 输出中的服务器端错误
  4. 测试工具列表： 手动测试服务器的工具发现 endpoint

工具无法执行

症状： 工具被发现但执行时失败

排查步骤：

  1. 参数验证： 确保你的 tool 能接受预期的参数
  2. Schema 兼容性： 验证你的 input schemas 是有效的 JSON Schema
  3. 错误处理： 检查你的 tool 是否抛出了未处理的异常
  4. 超时问题： 考虑增加 timeout 设置

沙盒兼容性

症状： 启用沙盒时 MCP servers 失败

解决方案：

  1. 基于 Docker 的 servers： 使用包含所有依赖的 Docker 容器
  2. 路径可访问性： 确保 server 可执行文件在沙盒中可用
  3. 网络访问： 配置沙盒以允许必要的网络连接
  4. 环境变量： 验证所需的环境变量已正确传递

调试技巧

  1. 启用调试模式： 使用 --debug 参数运行 CLI 以获取详细输出
  2. 检查 stderr： MCP 服务器的 stderr 会被捕获并记录（INFO 级别消息会被过滤）
  3. 独立测试： 在集成之前，先独立测试你的 MCP 服务器
  4. 增量配置： 从简单工具开始，再逐步添加复杂功能
  5. 频繁使用 /mcp： 在开发过程中监控服务器状态

重要说明

安全注意事项

  • 信任设置： trust 选项会跳过所有确认对话框。请谨慎使用，仅用于你完全控制的服务器
  • 访问令牌： 配置包含 API keys 或 tokens 的环境变量时，要注意安全性
  • 沙箱兼容性： 使用沙箱时，确保 MCP 服务器在沙箱环境中可用
  • 私有数据： 使用范围过广的 personal access tokens 可能导致不同仓库间的信息泄露

性能与资源管理

  • 连接持久化： CLI 会对成功注册工具的服务器保持持久连接
  • 自动清理： 对于不提供任何工具的服务器，其连接会被自动关闭
  • 超时管理： 根据服务器响应特性配置合适的超时时间
  • 资源监控： MCP 服务器作为独立进程运行，会消耗系统资源

Schema 兼容性

  • 属性剥离： 系统会自动移除某些 schema 属性（如 $schema、additionalProperties），以确保与 Qwen API 的兼容性
  • 名称清理： 工具名称会自动进行清理，以满足 API 要求
  • 冲突解决： 若多个服务器之间出现工具名称冲突，系统将通过自动添加前缀的方式解决

这种全面的集成机制，使 MCP 服务器成为扩展 CLI 功能的强大方式，同时兼顾了安全性、可靠性和易用性。

从工具返回富内容

MCP 工具不仅限于返回简单的文本。你可以返回丰富的多部分的内容，包括文本、图像、音频和其他二进制数据，所有这些都在单个工具响应中完成。这使你能够构建强大的工具，在一次交互中为模型提供多样化的信息。

所有从工具返回的数据都会被处理并作为上下文发送给模型，用于下一次生成，使模型能够对提供的信息进行推理或总结。

工作原理

要返回富内容，你的工具响应必须遵循 MCP 规范中对 CallToolResult 的要求。结果的 content 字段应该是一个 ContentBlock 对象数组。CLI 会正确处理这个数组，将文本与二进制数据分离，并打包传递给模型。

你可以在 content 数组中混合使用不同类型的 content block。支持的 block 类型包括：

  • text
  • image
  • audio
  • resource（嵌入内容）
  • resource_link

示例：返回文本和图像

以下是一个有效的 MCP 工具 JSON 响应示例，该响应同时返回文本描述和图像：

{
  "content": [
    {
      "type": "text",
      "text": "Here is the logo you requested."
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA_HERE",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "The logo was created in 2025."
    }
  ]
}

当 Qwen Code 接收到此响应时，它将：

  1. 提取所有文本并将其合并为一个单独的 functionResponse 部分，供模型使用。
  2. 将图像数据作为独立的 inlineData 部分呈现。
  3. 在 CLI 中提供清晰、用户友好的摘要，表明已接收到文本和图像。

这使你能够构建功能强大的工具，为 Qwen 模型提供丰富的多模态上下文。

MCP Prompts 作为斜杠命令

除了工具之外，MCP 服务器还可以暴露预定义的 prompts，这些 prompts 可以作为斜杠命令在 Qwen Code 中执行。这允许你为常见或复杂的查询创建快捷方式，通过名称即可轻松调用。

在服务器端定义 Prompts

下面是一个定义了 prompts 的 stdio MCP server 小示例：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
 
const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});
 
server.registerPrompt(
  'poem-writer',
  {
    title: 'Poem Writer',
    description: 'Write a nice haiku',
    argsSchema: { title: z.string(), mood: z.string().optional() },
  },
  ({ title, mood }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}. Note that a haiku is 5 syllables followed by 7 syllables followed by 5 syllables `,
        },
      },
    ],
  }),
);
 
const transport = new StdioServerTransport();
await server.connect(transport);

这段代码可以通过以下方式添加到 settings.json 中的 mcpServers 字段下：

{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["filename.ts"]
    }
  }
}

调用 Prompts

一旦发现某个 prompt，你可以通过其名称作为斜杠命令来调用它。CLI 会自动处理参数解析。

/poem-writer --title="Qwen Code" --mood="reverent"

或者，使用位置参数：

/poem-writer "Qwen Code" reverent

当你运行这个命令时，CLI 会在 MCP server 上执行 prompts/get 方法，并传入提供的参数。server 负责将参数替换到 prompt 模板中并返回最终的 prompt 文本。然后 CLI 将此 prompt 发送给模型执行。这为自动化和共享常见工作流提供了一种便捷的方式。

使用 qwen mcp 管理 MCP 服务器

虽然你始终可以通过手动编辑 settings.json 文件来配置 MCP 服务器，但 CLI 提供了一套便捷的命令，可以让你以编程方式管理服务器配置。这些命令简化了添加、列出和删除 MCP 服务器的过程，无需直接编辑 JSON 文件。

添加服务器 (qwen mcp add)

add 命令用于在你的 settings.json 中配置一个新的 MCP 服务器。根据作用域 (-s, --scope)，该配置将被添加到用户配置文件 ~/.qwen/settings.json 或项目配置文件 .qwen/settings.json 中。

命令格式：

qwen mcp add [options] <name> <commandOrUrl> [args...]
  • <name>: 服务器的唯一名称。
  • <commandOrUrl>: 要执行的命令（用于 stdio 模式）或 URL（用于 http/sse 模式）。
  • [args...]: 可选参数，仅适用于 stdio 模式的命令。

选项（Flags）：

  • -s, --scope: 配置作用域（user 或 project）。[默认值: “project”]
  • -t, --transport: 传输类型（stdio, sse, http）。[默认值: “stdio”]
  • -e, --env: 设置环境变量（例如：-e KEY=value）。
  • -H, --header: 为 SSE 和 HTTP 传输设置 HTTP headers（例如：-H “X-Api-Key: abc123” -H “Authorization: Bearer abc123”）。
  • --timeout: 设置连接超时时间（单位：毫秒）。
  • --trust: 信任该服务器（跳过所有工具调用确认提示）。
  • --description: 设置服务器描述信息。
  • --include-tools: 包含的工具列表，以逗号分隔。
  • --exclude-tools: 排除的工具列表，以逗号分隔。

添加 stdio server

这是运行本地 server 的默认传输方式。

 
# 基本语法
qwen mcp add <name> <command> [args...]
 
# 示例：添加一个本地 server
qwen mcp add my-stdio-server -e API_KEY=123 /path/to/server arg1 arg2 arg3
 
# 示例：添加一个本地 Python server
qwen mcp add python-server python server.py --port 8080

添加 HTTP server

此传输方式适用于使用流式 HTTP 传输的 server。

 
# 基本语法
qwen mcp add --transport http <name> <url>
 
# 示例：添加一个 HTTP server
qwen mcp add --transport http http-server https://api.example.com/mcp/
 
# 示例：添加带认证 header 的 HTTP server
qwen mcp add --transport http secure-http https://api.example.com/mcp/ --header "Authorization: Bearer abc123"

添加 SSE server

此传输方式适用于使用 Server-Sent Events (SSE) 的 server。

 
# 基本语法
qwen mcp add --transport sse <name> <url>

示例：添加一个 SSE 服务器

qwen mcp add —transport sse sse-server https://api.example.com/sse/ 

示例：添加一个带认证 header 的 SSE 服务器

qwen mcp add —transport sse secure-sse https://api.example.com/sse/  —header “Authorization: Bearer abc123”


### 列出服务器 (`qwen mcp list`)

要查看当前已配置的所有 MCP 服务器，可以使用 `list` 命令。该命令会显示每个服务器的名称、配置详情以及连接状态。

**命令：**

```bash
qwen mcp list

示例输出：

✓ stdio-server: command: python3 server.py (stdio) - Connected
✓ http-server: https://api.example.com/mcp (http) - Connected
✗ sse-server: https://api.example.com/sse (sse) - Disconnected

删除服务器 (qwen mcp remove)

要从配置中删除一个服务器，请使用 remove 命令并指定服务器名称。

命令：

qwen mcp remove <name>

示例：

qwen mcp remove my-server

该命令会根据作用域 (-s, --scope) 在相应的 settings.json 文件中查找并删除 mcpServers 对象里的 “my-server” 条目。

Last updated on
内存子代理