Skip to main content
Glama
HUAN425

qwen-mcp

by HUAN425
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
JavaScript
Remote

Reasonix Qwen MCP Server

专为 Reasonix 设计的 MCP 插件：把阿里云百炼（DashScope）的通义千问（Qwen）模型接入 Reasonix，提供视觉理解、联网搜索、通用对话三个工具。 A Qwen MCP server built for Reasonix: vision understanding, real web search and chat via Alibaba Cloud DashScope.

一个轻量 Node.js MCP server，提供三个即用工具：视觉理解（qwen3-vl-plus）、真实联网搜索（enable_search）、通用文本对话（qwen-plus）。

A lightweight Node.js MCP server exposing three ready-to-use tools: vision (qwen3-vl-plus), real web search (enable_search), chat (qwen-plus).

📖 详细中文使用手册：使用说明.md

✨ 功能特性 / Features

工具 / Tool

说明 / Description

模型 / Model

qwen_vision

视觉理解：传本地图片路径或 http(s) 图片 URL，让模型"看图"并回答

qwen3-vl-plus

qwen_search

联网搜索：实时检索最新信息，返回带来源的综合回答

qwen-plus

qwen_chat

通用文本对话（总结 / 翻译 / 改写 / 写代码等）

qwen-plus

关键特性：

  • 🖼️ 视觉提速：本地图片自动用 sharp 预压缩（>300KB 或分辨率 >1568px 才压缩，小图零损耗），网络图片先下载压缩再送模型（下载限 10MB）；

  • 🔍 真联网：走百炼原生接口的 enable_search（OpenAI 兼容端点会静默忽略该参数，详见下方"工作原理"）；

  • ⚡ 生成长度可控：max_tokens 参数随时可调，快慢由你决定；

  • 🔐 Key 安全：支持环境变量 DASHSCOPE_API_KEY 或本地 config.json（已被 .gitignore 忽略，不会入库）。

Related MCP server: MCP Server with OpenAI Integration

📦 环境要求 / Requirements

🚀 快速开始 / Quick Start

🤖 Reasonix 用户：无需手动配置——克隆/下载本项目后，在 Reasonix 中打开项目目录，直接让 Reasonix "安装并配置这个 MCP 插件"，它会自动注册、连接并引导你填写 API Key。

1. 安装 / Install

git clone https://github.com/HUAN425/reasonix-qwen-mcp.git qwen-mcp
cd qwen-mcp
npm install

2. 配置 / Configure

二选一：

方式 A：环境变量（推荐）

# Windows PowerShell
$env:DASHSCOPE_API_KEY = "sk-..."

# macOS / Linux
export DASHSCOPE_API_KEY="sk-..."

方式 B：配置文件

cp config.example.json config.json   # Windows: copy config.example.json config.json
# 然后编辑 config.json 填入 apiKey

config.json 支持的自定义项：

{
  "apiKey": "sk-...",                                  // 必填；环境变量优先
  "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", // 可选；仅影响对话与视觉，联网搜索固定使用国内原生端点
  "visionModel": "qwen3-vl-plus",                      // 可选，视觉模型
  "searchModel": "qwen-plus",                          // 可选，搜索模型
  "chatModel": "qwen-plus"                             // 可选，对话模型
}

注意：修改 config.json 后需重启 MCP server 生效（配置有进程内缓存）。

3. 注册到 MCP 客户端 / Register with your client

⚠️ 兼容性说明：本项目目前仅在 Reasonix 上实际测试使用过。技术实现基于标准 MCP 协议（stdio 传输），理论上适用于其他支持 MCP 的客户端（如 Claude Desktop、Cursor 等），但尚未在它们上面实测验证。如在其他客户端遇到问题，欢迎反馈。

Claude Desktop — claude_desktop_config.json：

{
  "mcpServers": {
    "qwen-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qwen-mcp/server.js"]
    }
  }
}

项目级 .mcp.json（Reasonix 等支持）：

{
  "mcpServers": {
    "qwen-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qwen-mcp/server.js"]
    }
  }
}

4. 使用 / Usage

三个工具会以 mcp__qwen-mcp__qwen_vision 等名称出现在你的客户端里。

工具

参数

说明

qwen_vision

image（必填）、prompt、detail（low/high）、max_tokens

image 支持本地绝对/相对路径或 http(s) URL；默认输出 150 字内简要描述、max_tokens=800

qwen_search

query（必填）、max_tokens

返回头标注 [已联网检索 N 条实时结果]，未联网时会明确提示

qwen_chat

message（必填）

纯文本对话

⚙️ 工作原理 / How it works

  • 对话与视觉：调用 DashScope OpenAI 兼容端点 POST /compatible-mode/v1/chat/completions（多模态走 image_url + base64 data URL）；

  • 联网搜索：调用百炼原生端点 POST /api/v1/services/aigc/text-generation/generation 并携带 enable_search: true。

    ⚠️ 实测：OpenAI 兼容端点会静默忽略 enable_search（返回模型自身知识而非实时结果），所以搜索必须走原生端点。

🧪 测试 / Test

npm test   # 等价于 node test-handshake.js（MCP 握手 + 工具列表，无需 API Key）

📁 项目结构 / Structure

qwen-mcp/
├── server.js            # MCP server 主程序
├── config.example.json  # 配置模板（复制为 config.json 使用）
├── package.json
├── .gitignore
└── test-handshake.js    # 握手自测脚本

🔒 安全说明 / Security

  • config.json、node_modules/ 已在 .gitignore 中，不会提交到仓库；

  • 请勿将任何真实 API Key 写入会进入版本库的文件；

  • ⚠️ qwen_vision 可读取本机任意路径的图片文件并发送至阿里云，请仅在可信环境使用；网络图片下载上限 10MB，超限自动回退原 URL。

📄 许可证 / License

MIT

⚠️ 免责声明 / Disclaimer

本项目与阿里云无官方关联。模型能力、价格与接口行为以百炼官方文档为准。

Available Tools

3 tools
qwen_chatA

与通义千问文本模型进行普通对话（不联网），用于总结、改写、翻译、代码生成等通用任务

ParametersJSON Schema
NameRequiredDescriptionDefault
messageYes要发送给模型的消息内容

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the key behavioral trait of not being connected to the internet, which is a critical limitation for a chat model. It does not discuss other behaviors like statelessness or rate limits, but for a simple single-message chat tool, this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire description is a single well-structured sentence that front-loads the core purpose ('ordinary conversation'), then adds the key constraint ('not connected to internet'), and ends with concrete examples. Every word contributes value, and there is no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (one required parameter, no output schema, no annotations), the description is fully sufficient. It explains what the tool does, provides examples, and clarifies the offline nature, which is all an agent needs to decide when and how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully describes the 'message' parameter (the message content to send), so the schema coverage is 100%. The tool description adds context about the kinds of tasks the message can be used for, but it does not enrich the parameter semantics beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that this tool performs ordinary conversations with the Tongyi Qianwen text model, specifically without internet access. It lists common use cases (summarizing, rewriting, translating, code generation) and distinguishes itself from sibling tools like qwen_search (internet-connected) and qwen_vision (vision-based) by specifying 'text model' and 'not connected to internet'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for general text tasks that do not require internet access, which sets expectations. However, it does not explicitly mention when to use qwen_chat over alternatives (e.g., 'use qwen_search when internet is needed'), so the guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

qwen_visionA

用通义千问视觉模型 qwen3-vl-plus 理解一张图片（支持本地文件路径或 http(s) 图片 URL），并回答关于图片的问题

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYes本地图片路径（绝对路径，或相对当前工作目录）或 http(s) 图片 URL
detailNo视觉采样分辨率：low 更快更省，high 细节更清晰（默认 low）
promptNo关于图片的问题或指令；省略时默认要求模型简要描述（150 字内）
max_tokensNo回答最大 token 数（默认 800；调低更快，调高更详细）

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It adds useful context by naming the specific model and explaining the default prompt behavior (150-word description). However, it does not disclose potential error conditions, rate limits, or detailed return format, which leaves gaps given the absence of annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the core purpose, model name, and input types. No redundant words, and it efficiently covers the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderate complexity and the presence of a detailed schema, the description sufficiently covers the tool's purpose and default behavior. It does not have an output schema, but the phrase 'answer questions about the image' adequately implies the return value. Minor gaps remain on error handling/edge cases, so it isn't a perfect 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with all four parameters already explained in the schema. The description adds the model name and overall purpose but does not enrich the understanding of individual parameters beyond what the schema provides. Hence a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: using the qwen3-vl-plus vision model to understand an image and answer questions about it. It specifies both the verb (understand/answer) and resource (image), and by emphasizing image input it distinctly separates itself from sibling tools qwen_search and qwen_chat.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for image-related tasks by stating it handles local file paths or URLs and answers image questions. It gives a clear context but does not explicitly mention alternatives or exclusions; thus it stops short of a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedqwen_chat
    • First observedqwen_search
    • First observedqwen_vision
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: qwen_vision for image understanding, qwen_search for internet-connected queries, and qwen_chat for general text conversations. There is no overlap in functionality, so an agent can easily select the right tool.

Naming Consistency5/5

All tools follow a consistent qwen_<capability> naming pattern, using lower_snake_case. The suffix clearly indicates the tool's function, making the naming predictable and uniform.

Tool Count5/5

With 3 tools, the server is tightly scoped for its purpose of providing Qwen model access across vision, search, and chat. Each tool serves a distinct core need without unnecessary bloat.

Completeness4/5

The set covers the primary use cases for a language model server: image understanding, live information retrieval, and general text tasks. However, missing capabilities like audio processing or multi-turn conversation management are minor gaps that can be worked around.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Agent中国通

    FRANhss
    A
    license
    A
    quality
    D
    maintenance
    这是一个面向中文圈的MCP服务器，将中国互联网常用能力（如地图、快递、RSS、B站等）封装为标准MCP工具，方便AI Agent安全调用。
    13
    2
    MIT

  • Hermes MCP Server

    718haxi
    F
    license
    Not graded
    quality
    B
    maintenance
    A lightweight Node.js MCP server with zero dependencies offering 9 built-in tools for system info, web fetching, GitHub search, file operations, shell execution, and key-value memory, enabling AI agents to perform these tasks via the Model Context Protocol.
    -