qwen-api-mcp

v1.0.48

Published

3 months ago

Qwen API MCP Server - 提供聊天、图片生成和获取图片功能

0High
0Medium
0Low

qingtingnpm

mcp qwen chat image-generation api npx modelscope

Qwen API MCP Server

一个支持 npx 直接启动的 Qwen API MCP (Model Context Protocol) 服务器，提供聊天、图片生成和获取图片功能，无需安装即可使用！

✨ 功能特性

💬 聊天功能: 与Qwen3大语言模型进行智能对话
🖼️ 图片生成: 使用Qwen-Image模型生成高质量图片
📋 状态查询: 实时查询图片生成任务状态
🔗 结果获取: 获取已完成的图片生成结果
🚀 npx支持: 无需安装，直接运行
🔒 安全可靠: API密钥安全，支持环境变量管理
🐛 调试友好: 详细的调试日志和错误提示
⚡ 轻量级: 包体积小，启动快速

🚀 快速开始

方式1: 直接使用npx启动（推荐）

# 设置API密钥环境变量
export MODELSCOPE_API_KEY=your_api_key_here

# 启动MCP服务器（自动确认安装）
npx --yes qwen-api-mcp

# 或者如果已安装过，直接运行
npx qwen-api-mcp

# 或者指定具体版本
npx --yes [email protected]

方式2: 使用配置文件

在当前目录创建 .env 文件：

MODELSCOPE_API_KEY=your_api_key_here
DEBUG=true

然后启动：

npx qwen-api-mcp

方式3: 直接传递API密钥

npx qwen-api-mcp --key your_api_key_here

方式4: 全局安装

# 全局安装
npm install -g qwen-api-mcp

# 直接使用
qwen-api-mcp

📋 命令行选项

npx qwen-api-mcp [选项]

| 选项 | 描述 | 示例 | |------|------|------| | -h, --help | 显示帮助信息 | npx qwen-api-mcp --help | | -v, --version | 显示版本信息 | npx qwen-api-mcp --version | | -d, --debug | 启用调试模式 | npx qwen-api-mcp --debug | | --key <api_key> | 直接设置API密钥 | npx qwen-api-mcp --key xxx |

🔧 环境变量配置

| 环境变量 | 描述 | 必需 | 默认值 | 示例 | |----------|------|------|--------|------| | MODELSCOPE_API_KEY | ModelScope API密钥 | ✅ | 无 | ms-b428598d-e19a-4823-bd8e-d4335737e0c7 | | DEBUG | 调试模式 | ❌ | false | true | | MODELSCOPE_TIMEOUT | 请求超时时间(毫秒) | ❌ | 30000 | 60000 |

注意：API 基础地址已固定为 https://api-inference.modelscope.cn/，无需额外配置。

🎯 获取API密钥

访问 ModelScope
注册并登录账号
进入控制台获取API密钥
复制密钥格式类似：ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

🛠️ MCP工具

1. chat - 聊天对话

与Qwen3大语言模型进行智能对话。

参数:

prompt (必需): 聊天提示词或问题
model (可选): 模型名称，默认为 "qwen3"

示例:

{
  "name": "chat",
  "arguments": {
    "prompt": "你好，请简单介绍一下你自己"
  }
}

响应示例:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "model": "Qwen/Qwen3-235B-A22B-Instruct-2507",
          "content": "你好！我是Qwen3大语言模型...",
          "usage": {
            "prompt_tokens": 8,
            "completion_tokens": 25,
            "total_tokens": 33
          },
          "finish_reason": "stop"
        }
      }
    }
  ]
}

2. generate_image - 生成图片

使用Qwen-Image模型生成高质量图片。

参数:

prompt (必需): 图片描述提示词，越详细越好

示例:

{
  "name": "generate_image",
  "arguments": {
    "prompt": "一座美丽的山峰，在夕阳下呈现金色光芒，高清摄影风格，自然光线"
  }
}

响应示例:

{
  "content": [
    {
      "type": "text", 
      "text": {
        "success": true,
        "data": {
          "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881",
          "task_status": "PENDING",
          "request_id": "fdf7db12-545b-4c5a-b627-9f52c0019d5d",
          "message": "图片生成任务已创建，使用 get_image_status 查询状态"
        }
      }
    }
  ]
}

3. get_image_status - 查询图片状态

查询图片生成任务的实时状态。

参数:

task_id (必需): 图片生成任务的ID

示例:

{
  "name": "get_image_status",
  "arguments": {
    "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881"
  }
}

状态说明:

PENDING: 任务正在等待处理
PROCESSING: 任务正在处理中
SUCCEED: 任务处理成功
FAILED: 任务处理失败

4. get_image_result - 获取图片结果

获取已完成的图片生成任务的结果。

参数:

task_id (必需): 图片生成任务的ID

示例:

{
  "name": "get_image_result",
  "arguments": {
    "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881"
  }
}

成功响应示例:

{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881",
          "task_status": "SUCCEED",
          "image_url": "https://example.com/generated-image.jpg",
          "images": ["https://example.com/generated-image.jpg"],
          "message": "图片生成成功"
        }
      }
    }
  ]
}

📝 使用示例

Claude Desktop 配置

在Claude Desktop的配置文件中添加：

{
    "mcpServers": {
        "qwen-api": {
            "command": "npx",
            "args": [
                "--yes", "--no-cache",
                "[email protected]",
                "--token=your_actual_api_key_here"
            ],
            "disabled": false
        }
    }
}

⚠️ 重要提示：

推荐使用 --token=your_api_key 方式传递密钥，更安全可靠
不要使用 "${MODELSCOPE_API_KEY}"，这种变量替换在大多数MCP客户端中不被支持
如果仍想使用环境变量方式，也可以用以下配置：

{
    "mcpServers": {
        "qwen-api": {
            "command": "npx",
            "args": [
                "--yes", "--no-cache",
                "[email protected]"
            ],
            "env": {
                "MODELSCOPE_API_KEY": "your_actual_api_key_here",
                "DEBUG": "true"
            },
            "disabled": false
        }
    }
}

环境变量设置:

# macOS/Linux
export MODELSCOPE_API_KEY=your_api_key_here

# Windows
set MODELSCOPE_API_KEY=your_api_key_here

# PowerShell
$env:MODELSCOPE_API_KEY="your_api_key_here"

支持的新用法（推荐）:

# 使用 --token 参数
npx qwen-api-mcp --token=your_api_key_here

# 使用 --key 参数
npx qwen-api-mcp --key=your_api_key_here

基本使用流程

启动服务器:

npx qwen-api-mcp --debug

聊天对话:

{
  "name": "chat",
  "arguments": {
    "prompt": "请解释一下量子计算的基本原理"
  }
}

生成图片:

{
  "name": "generate_image", 
  "arguments": {
    "prompt": "一只可爱的橘猫在阳光下的窗台上睡觉"
  }
}

查询状态:

{
  "name": "get_image_status",
  "arguments": {
    "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881"
  }
}

获取结果:

{
  "name": "get_image_result",
  "arguments": {
    "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881"
  }
}

🔒 安全性

✅ API密钥安全: 从不在日志或输出中显示完整密钥
✅ 环境隔离: npx运行在临时环境中，不会污染系统
✅ 输入验证: 自动验证API密钥格式和长度
✅ 错误处理: 完善的错误捕获和处理机制
✅ HTTPS加密: 所有API请求都通过HTTPS传输

🐛 故障排除

常见问题

1. API密钥错误

❌ 错误: 未找到 MODELSCOPE_API_KEY 环境变量

解决方案:

# 方式1: 设置环境变量
export MODELSCOPE_API_KEY=your_key_here

# 方式2: 创建.env文件
echo "MODELSCOPE_API_KEY=your_key_here" > .env

# 方式3: 直接传递
npx qwen-api-mcp --key your_key_here

2. 网络连接问题

npx qwen-api-mcp --debug  # 查看详细错误信息

3. 图片生成失败

检查提示词是否合适
确认API配额是否充足
查看调试日志了解具体错误

4. 权限问题

# 确保有当前目录的写入权限
chmod 755 .

调试技巧

启用调试模式: npx qwen-api-mcp --debug
检查配置: 查看启动时的配置信息输出
环境变量检查: env | grep MODELSCOPE
网络测试: curl -I https://api-inference.modelscope.cn/

📊 性能优化

建议配置

# 增加超时时间（处理复杂图片生成）
export MODELSCOPE_TIMEOUT=60000

# 启用调试模式（开发时）
export DEBUG=true

最佳实践

图片提示词: 提供详细、具体的描述
批量操作: 合理安排图片生成，避免频繁请求
错误重试: 实现适当的重试机制
缓存结果: 缓存聊天和图片结果

📈 更新日志

v1.0.0

✨ 初始版本发布
🚀 支持npx直接启动
💬 聊天功能支持
🖼️ 图片生成功能
🔍 状态查询功能
📥 结果获取功能

🤝 贡献

欢迎提交Issue和Pull Request！

开发环境设置

# 克隆项目
git clone https://github.com/your-repo/qwen-api-mcp.git
cd qwen-api-mcp

# 安装依赖
npm install

# 运行测试
npm test

# 启动开发模式
npm start

📄 许可证

ISC License - 详见 LICENSE 文件

🔗 相关链接

📦 npm包 - npm包页面
🔑 ModelScope - 获取API密钥
📋 MCP协议 - 了解MCP协议
🐛 问题反馈 - 报告问题
💬 讨论区 - 功能讨论

🙏 致谢

感谢 ModelScope 提供强大的AI服务支持！

⚠️ 重要提示:

使用本工具需要有效的ModelScope API密钥
请遵守ModelScope的使用条款和政策
注意API调用频率限制和费用
生成的内容请遵守相关法律法规

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Qwen API MCP Server

✨ 功能特性

🚀 快速开始

方式1: 直接使用npx启动（推荐）

方式2: 使用配置文件

方式3: 直接传递API密钥

方式4: 全局安装

📋 命令行选项

🔧 环境变量配置

🎯 获取API密钥

🛠️ MCP工具

1. chat - 聊天对话

2. generate_image - 生成图片

3. get_image_status - 查询图片状态

4. get_image_result - 获取图片结果

📝 使用示例

Claude Desktop 配置

基本使用流程

🔒 安全性

🐛 故障排除

常见问题

调试技巧

📊 性能优化

建议配置

最佳实践

📈 更新日志

v1.0.0

🤝 贡献

开发环境设置

📄 许可证

🔗 相关链接

🙏 致谢