JinDaGe - qwen-mcp-tool MCP Details

article

README

🚀 Qwen MCP 工具

Qwen MCP 工具是一个用于 Qwen CLI 集成的模型上下文协议服务器。该工具允许像 Claude 这样的 AI 助手通过 MCP 协议，利用 Qwen 强大的代码分析和大上下文窗口能力。

🚀 快速开始

Qwen MCP 工具为 AI 助手与 Qwen 的集成提供了便利。在使用前，你需要确保满足一定的前提条件，并按照相应的步骤进行安装。

✨ 主要特性

大上下文窗口：利用 Qwen 巨大的令牌容量来分析大文件和整个代码库。
文件分析：使用 @filename 或 @directory 语法在查询中包含文件内容。
沙盒模式：在隔离环境中安全地执行代码和运行测试。
多模型支持：支持各种 Qwen 模型（如 qwen3-coder-plus、qwen3-coder-turbo 等）。
灵活的审批模式：通过 plan/default/auto-edit/yolo 模式控制工具执行。
MCP 协议：与支持 MCP 的 AI 助手无缝集成。

📦 安装指南

快速设置（最简单 - 推荐）

使用 Claude Code 内置的 MCP 安装程序：

claude mcp add qwen-cli -- npx -y @jaggerxtrm/qwen-mcp-tool

这一条命令将自动完成所有配置！

通过全局安装

通过 npm 进行安装：

npm install -g @jaggerxtrm/qwen-mcp-tool

然后添加到 Claude Code MCP 设置（~/.config/claude/mcp_settings.json）：

{
  "mcpServers": {
    "qwen-cli": {
      "command": "qwen-mcp-tool"
    }
  }
}

通过 npx（手动配置）

手动配置以使用 npx 而无需安装：

{
  "mcpServers": {
    "qwen-cli": {
      "command": "npx",
      "args": ["-y", "@jaggerxtrm/qwen-mcp-tool"]
    }
  }
}

从源代码安装（开发用途）

克隆仓库并安装依赖：

git clone <repo-url>
cd qwen-mcp-tool
npm install

构建项目：

npm run build

本地链接：

npm link

💻 使用示例

可用工具

ask-qwen

与 Qwen AI 交互的主要工具。参数：

prompt（必需）：你的问题或指令。
- 使用 @filename 包含文件内容。
- 使用 @directory 包含目录中的所有文件。
model（可选）：要使用的模型（如 qwen3-coder-plus、qwen3-coder-turbo 等）。
sandbox（可选）：启用沙盒模式以安全执行代码。
approvalMode（可选）：控制工具执行审批。
- plan：分析工具调用但不执行。
- default：提示进行审批（默认行为）。
- auto-edit：自动批准文件编辑。
- yolo：自动批准所有工具调用。
yolo（可选）：approvalMode='yolo' 的快捷方式。
allFiles（可选）：将当前目录中的所有文件作为上下文包含。
debug（可选）：启用调试模式。

示例：

// 分析特定文件
{
  "prompt": "@src/main.ts Explain what this code does"
}

// 分析整个代码库
{
  "prompt": "@src/ Summarize the architecture of this codebase"
}

// 使用特定模型并启用沙盒模式
{
  "prompt": "Run the test suite and fix any failures",
  "model": "qwen3-coder-plus",
  "sandbox": true,
  "approvalMode": "auto-edit"
}

ping

用于验证连接的简单回显测试。参数：

prompt（可选）：要回显的消息（默认为 "Pong!"）。

Help

显示 Qwen CLI 帮助信息。参数：无

📚 详细文档

配置

该工具使用以下默认模型：

主模型：qwen3-coder-plus
备用模型：qwen3-coder-turbo（当主模型达到配额限制时使用）

你可以在请求中指定 model 参数来覆盖这些默认设置。

与 Claude Code 配合使用

安装为 MCP 服务器后，你可以在 Claude Code 中使用它：

Ask Qwen to analyze the authentication system in @src/auth/

Claude 将自动使用 ask-qwen 工具并传递适当的参数。

项目结构

qwen-mcp-tool/
├── src/
│   ├── index.ts              # MCP 服务器入口点
│   ├── constants.ts          # 配置和常量
│   ├── tools/
│   │   ├── registry.ts       # 工具注册系统
│   │   ├── ask-qwen.tool.ts  # 主要的 Qwen 交互工具
│   │   ├── simple-tools.ts   # 实用工具（ping、help）
│   │   └── index.ts          # 工具导出
│   └── utils/
│       ├── commandExecutor.ts # 命令执行实用工具
│       ├── qwenExecutor.ts    # Qwen CLI 包装器
│       └── logger.ts          # 日志记录实用工具
├── package.json
├── tsconfig.json
└── README.md

工作原理

MCP 服务器通过 stdio 传输监听工具调用。
当调用工具时，服务器使用 Zod 模式验证参数。
对于 ask-qwen，提示将通过适当的标志传递给 Qwen CLI。
文件引用（@filename）由 Qwen 内置的文件处理功能处理。
捕获输出并返回给 MCP 客户端。
如果达到配额限制，服务器将自动切换到 turbo 模型。

与 Gemini MCP 工具的比较

本工具受 gemini-mcp-tool 启发，但针对 Qwen CLI 进行了调整： | 特性 | Gemini MCP | Qwen MCP | |---------|-----------|----------| | 文件引用 | ✅ | ✅（更高级） | | 沙盒模式 | ✅ | ✅ | | 多模型支持 | ✅ | ✅ | | 审批模式 | ❌ | ✅ | | 目录遍历 | 基础 | 高级（支持 git） | | 多模态支持 | 有限 | 支持图像、PDF、音频、视频 |

故障排除

"Qwen CLI 未找到"

确保 Qwen CLI 已安装并在你的 PATH 中可用：

npm install -g @qwen/cli
# 或遵循 https://github.com/QwenLM/qwen-code 中的说明

"命令超时"

对于非常大的文件或代码库，分析可能需要比默认的 10 分钟超时时间更长的时间。可以考虑：

使用 .qwenignore 排除不必要的文件。
将大查询拆分为较小的块。
使用 approvalMode: "plan" 进行分析而不执行。

"无效的工具参数"

检查你的参数是否符合工具模式。使用 Help 工具查看可用选项。

📄 许可证

本项目采用 MIT 许可证。

贡献

欢迎贡献！请随时提交问题或拉取请求。

鸣谢

本项目受 jamubc 的 gemini-mcp-tool 启发，专为与 Qwen Code 配合使用而构建。

qwen-mcp-tool