Skip to Content
开发者指南工具MCP 服务器

使用 Qwen Code 的 MCP 服务器

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

什么是 MCP 服务器？

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

MCP 服务器使 CLI 能够：

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

通过 MCP 服务器，你可以扩展 CLI 的功能，执行超出其内置功能的操作，例如与数据库、API、自定义脚本或专用工作流进行交互。

核心集成架构

Qwen Code 通过内置在核心包 (packages/core/src/tools/) 中的复杂发现和执行系统与 MCP 服务器集成：

发现层 (mcp-client.ts)

发现过程由 discoverMcpTools() 协调，该函数：

  1. 遍历配置的服务器，从你的 settings.json 中的 mcpServers 配置获取
  2. 建立连接，使用适当的传输机制（Stdio、SSE 或可流式 HTTP）
  3. 从每个服务器获取工具定义，使用 MCP 协议
  4. 清理和验证 工具模式，确保与 Qwen API 兼容
  5. 在全局工具注册表中注册工具，并解决冲突

执行层 (mcp-tool.ts)

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

  • 基于服务器信任设置和用户偏好处理确认逻辑
  • 通过使用正确参数调用 MCP 服务器来管理工具执行
  • 处理响应，用于 LLM 上下文和用户显示
  • 维护连接状态 并处理超时

传输机制

CLI 支持三种 MCP 传输类型：

  • Stdio 传输： 生成子进程并通过 stdin/stdout 进行通信
  • SSE 传输： 连接到服务器发送事件端点
  • 可流式 HTTP 传输： 使用 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 头
  • 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 客户端 ID。与 authProviderType: 'service_account_impersonation' 一起使用。
  • targetServiceAccount (string): 要模拟的 Google Cloud 服务账户的电子邮件地址。与 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 流程和令牌管理

认证流程

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

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

浏览器重定向要求

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

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

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

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

管理 OAuth 认证

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

 
# 列出需要认证的服务器
/mcp auth

与特定服务器进行身份验证

/mcp auth serverName

如果令牌过期则重新进行身份验证

/mcp auth serverName


#### OAuth 配置属性

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

#### 令牌管理

OAuth 令牌会自动：

- **安全存储**在 `~/.qwen/mcp-oauth-tokens.json` 中
- **刷新**过期的令牌（如果有刷新令牌可用）
- 在每次连接尝试前**验证**令牌
- 无效或过期时**清理**令牌

#### 认证提供程序类型

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

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

#### Google 凭据

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

服务账号模拟

要使用服务账号模拟对服务器进行身份验证，你必须将 authProviderType 设置为 service_account_impersonation 并提供以下属性：

  • targetAudience (string): OAuth 客户端 ID，允许访问你尝试访问的 IAP 保护应用程序。
  • targetServiceAccount (string): 要模拟的 Google Cloud 服务账号的邮箱地址。

CLI 将使用你的本地应用程序默认凭据 (ADC) 为指定的服务账号和受众生成 OIDC ID 令牌。然后该令牌将用于与 MCP 服务器进行身份验证。

设置说明

  1. 创建  或使用现有的 OAuth 2.0 客户端 ID。 要使用现有的 OAuth 2.0 客户端 ID，请按照 如何共享 OAuth 客户端  中的步骤操作。
  2. 将 OAuth ID 添加到应用程序的程序化访问  允许列表中。 由于 Cloud Run 尚未成为 gcloud iap 中受支持的资源类型，你必须在项目上将客户端 ID 加入允许列表。
  3. 创建服务账号。 文档 ，Cloud Console 链接 
  4. 在 Cloud Run 服务本身的 “Security” 选项卡中或通过 gcloud，将服务账号和用户都添加到 IAP 策略中
  5. 授予所有将访问 MCP 服务器的用户和组 模拟服务账号  所需的权限（即 roles/iam.serviceAccountTokenCreator）。
  6. 为你的项目启用  IAM Credentials API。

配置示例

Python MCP 服务器 (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 服务器 (Stdio)

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

基于 Docker 的 MCP 服务器

{
  "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 服务器

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

带自定义头部的基于 HTTP 的 MCP 服务器

{
  "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 服务器

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

使用服务账号模拟的 SSE MCP 服务器

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

发现过程深入解析

当 Qwen Code 启动时，它会通过以下详细过程执行 MCP 服务器发现：

1. 服务器迭代和连接

对于 mcpServers 中的每个配置服务器：

  1. 状态跟踪开始： 服务器状态设置为 CONNECTING
  2. 传输选择： 基于配置属性：
    • httpUrl → StreamableHTTPClientTransport
    • url → SSEClientTransport
    • command → StdioClientTransport
  3. 连接建立： MCP 客户端尝试使用配置的超时时间进行连接
  4. 错误处理： 连接失败会被记录，服务器状态设置为 DISCONNECTED

2. 工具发现

连接成功后：

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

3. 冲突解决

当多个服务器暴露具有相同名称的工具时：

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

4. 模式处理

工具参数模式会进行清理以确保 API 兼容性：

  • $schema 属性 会被移除
  • additionalProperties 会被剥离
  • 带有 default 的 anyOf 会移除其默认值（与 Vertex AI 兼容）
  • 递归处理 适用于嵌套模式

5. 连接管理

发现后：

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

工具执行流程

当模型决定使用 MCP 工具时，会发生以下执行流程：

1. 工具调用

模型生成一个 FunctionCall，包含：

  • 工具名称： 注册的名称（可能带有前缀）
  • 参数： 与工具参数模式匹配的 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
  • 服务器详情： 配置摘要（不包括敏感数据）
  • 可用工具： 来自每个服务器的工具列表及其描述
  • 发现状态： 整体发现过程状态

/mcp 输出示例

MCP 服务器状态：

📡 pythonTools (已连接)
  命令: python -m my_mcp_server --port 8080
  工作目录: ./mcp-servers/python
  超时: 15000ms
  工具: calculate_sum, file_analyzer, data_processor

🔌 nodeServer (已断开)
  命令: node dist/server.js --verbose
  错误: 连接被拒绝

🐳 dockerizedServer (已连接)
  命令: docker run -i --rm -e API_KEY my-mcp-server:latest
  工具: docker__deploy, docker__status

发现状态: 已完成

工具使用

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

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

状态监控和故障排除

连接状态

MCP 集成跟踪几种状态：

服务器状态 (MCPServerStatus)

  • DISCONNECTED： 服务器未连接或出现错误
  • CONNECTING： 连接尝试正在进行中
  • CONNECTED： 服务器已连接并就绪

发现状态 (MCPDiscoveryState)

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

常见问题和解决方案

服务器无法连接

症状： 服务器显示 DISCONNECTED 状态

故障排除：

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

未发现工具

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

故障排除：

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

工具未执行

症状： 工具被发现但在执行期间失败

故障排除：

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

沙箱兼容性

症状： 启用沙箱时 MCP 服务器失败

解决方案：

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

调试技巧

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

重要注意事项

安全考虑

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

性能和资源管理

  • 连接持久性： CLI 与成功注册工具的服务器保持持久连接
  • 自动清理： 自动关闭与未提供工具的服务器的连接
  • 超时管理： 根据服务器的响应特性配置适当的超时时间
  • 资源监控： MCP 服务器作为独立进程运行并消耗系统资源

模式兼容性

  • 模式合规模式： 默认情况下（schemaCompliance: "auto"），工具模式会原样传递。在 settings.json 中设置 "model": { "generationConfig": { "schemaCompliance": "openapi_30" } } 以将模型转换为严格的 OpenAPI 3.0 格式。
  • OpenAPI 3.0 转换： 启用 openapi_30 模式时，系统会处理：
    • 可空类型：["string", "null"] -> type: "string", nullable: true
    • 常量值：const: "foo" -> enum: ["foo"]
    • 排他限制：数值 exclusiveMinimum -> 带 minimum 的布尔形式
    • 关键字移除：$schema、$id、dependencies、patternProperties
  • 名称清理： 工具名称会自动清理以满足 API 要求
  • 冲突解决： 服务器之间的工具名称冲突通过自动前缀解决

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

从工具返回富内容

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

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

工作原理

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

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

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

示例：返回文本和图像

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

{
  "content": [
    {
      "type": "text",
      "text": "这是你请求的 logo。"
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA_HERE",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "该 logo 创建于 2025 年。"
    }
  ]
}

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

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

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

MCP 提示作为斜杠命令

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

在服务器上定义提示

这是一个定义提示的小型 stdio MCP 服务器示例：

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

调用提示

一旦发现提示，你可以使用其名称作为斜杠命令来调用它。CLI 将自动处理参数解析。

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

或者，使用位置参数：

/poem-writer "Qwen Code" reverent

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

使用 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 命令的可选参数。

选项（标志）：

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

添加 stdio 服务器

这是运行本地服务器的默认传输方式。

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

添加 HTTP 服务器

此传输方式用于使用可流式 HTTP 传输的服务器。

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

添加 SSE 服务器

此传输方式用于使用服务器发送事件（SSE）的服务器。

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

示例：添加 SSE 服务器

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

示例：添加带认证头的 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) - 已连接
✓ http-server: https://api.example.com/mcp (http) - 已连接
✗ sse-server: https://api.example.com/sse (sse) - 已断开连接

删除服务器 (qwen mcp remove)

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

命令：

qwen mcp remove <name>

示例：

qwen mcp remove my-server

这将根据作用域 (-s, --scope) 在相应的 settings.json 文件中找到并删除 mcpServers 对象中的 “my-server” 条目。

Last updated on
内存Qwen Code 扩展