实战：使用 Qwen-Agent 调用自定义 MCP 服务

📌 前言

随着大模型应用的发展，如何让 LLM（大语言模型）安全、标准地访问本地数据或第三方工具成为了核心痛点。Model Context Protocol (MCP) 应运而生，它提供了一种标准化的方式连接 AI 模型与数据源。

本文将带大家通过 Python 实战，利用阿里云的 Qwen-Agent 框架，结合 MCP 协议，开发一个能够管理和分析桌面 TXT 文件的智能助手。

你将学到：

1. 如何使用 FastMCP 快速构建一个自定义的 MCP Server。
2. 如何在 Qwen-Agent 中配置并调用 MCP 工具。
3. 实现一个具有 Web UI 的本地文件管理智能体。

---

🛠️ 环境准备

在开始之前，请确保你已经安装了以下依赖库，并且拥有阿里云 DashScope 的 API Key。

pip install qwen-agent mcp dashscope

项目结构：

建议将代码文件放在同一目录下：

• txt_counter.py (MCP 服务端)
• assistant_mcp_txt_bot.py (Agent 客户端)

---

🚀 第一步：构建 MCP 服务端 (txt_counter.py)

我们需要一个服务来通过 MCP 协议暴露本地桌面的文件操作能力。这里我们使用 mcp 库中的 FastMCP 快速实现。

代码解析

这个脚本定义了三个工具：

1. count_desktop_txt_files: 统计桌面 TXT 文件数量。
2. list_desktop_txt_files: 列出文件名。
3. read_txt_file: 读取具体文件内容。

注意： 代码中硬编码了路径 D:/Desktop，请根据你的实际电脑环境修改（例如 Mac 用户改为 /Users/yourname/Desktop）。

import os
from pathlib import Path
from mcp.server.fastmcp import FastMCP

# 创建 MCP Server，命名为"桌面 TXT 文件统计器"
mcp = FastMCP("桌面 TXT 文件统计器")

# 请根据实际情况修改此路径
DESKTOP_PATH = Path(os.path.expanduser("D:/Desktop")) 

@mcp.tool()
def count_desktop_txt_files():
    """统计桌面上 .txt 文件的数量"""
    txt_files = list(DESKTOP_PATH.glob("*.txt"))
    return len(txt_files)

@mcp.tool()
def list_desktop_txt_files():
    """获取桌面上所有 .txt 文件的列表"""
    txt_files = list(DESKTOP_PATH.glob("*.txt"))
    
    if not txt_files:
        return "桌面上没有找到 .txt 文件。"
    
    # 格式化文件名列表
    file_list = "\n".join([f"- {file.name}" for file in txt_files])
    return f"在桌面上找到 {len(txt_files)} 个 .txt 文件：\n{file_list}"

@mcp.tool()
def read_txt_file(filename: str):
    """读取指定txt文件的内容"""
    file_path = DESKTOP_PATH / filename

    if not file_path.exists():
        return f"错误：文件 '{filename}' 不存在于桌面上。"
    
    if file_path.suffix.lower() != '.txt':
        return f"错误：文件 '{filename}' 不是txt文件。"

    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            content = f.read()
        return f"文件 '{filename}' 的内容：\n\n{content}"
    except Exception as e:
        return f"读取文件时发生错误：{str(e)}"

if __name__ == "__main__":
    # 初始化并运行服务器
    mcp.run()

---

🤖 第二步：构建 Qwen-Agent 客户端 (assistant_mcp_txt_bot.py)

接下来，我们编写 Agent 的主程序。这里使用的是阿里云开源的 Qwen-Agent 框架，它内置了对 function calling 的完美支持，并且可以非常容易地集成 GUI。

核心配置：连接 MCP

这是最关键的一步。我们不需要手动启动 MCP 服务器，而是让 Agent 通过 stdio (标准输入输出) 的方式启动并连接 Python 脚本。

# MCP 工具配置
tools = [{
    "mcpServers": {
        "txt-counter": {
            "command": "python",   # 执行命令
            "args": ["txt_counter.py"], # 参数，指向我们的MCP脚本
            # "port": 6277 # 注意：如果是stdio模式，通常不需要指定port，除非是SSE模式
        }
    }
}]

(注：原代码中的 port 在 stdio 模式下可能被忽略，取决于 qwen-agent 具体版本的实现，这里主要通过 command 启动子进程交互)

完整 Agent 代码

import os
import dashscope
from qwen_agent.agents import Assistant
from qwen_agent.gui import WebUI

# 配置 DashScope API Key
dashscope.api_key = os.getenv('DASHSCOPE_API_KEY', '您的API_KEY') 

def init_agent_service():
    """初始化文本计数助手服务"""
    
    # LLM 模型配置：使用强大的 qwen-max
    llm_cfg = {
        'model': 'qwen-max',
    }

    # 系统提示词
    system = ('你扮演一个文本分析助手，你可以读取用户的本地桌面文件。'
              '你可以帮助用户统计文件数量、列出文件、读取内容并进行分析（如字数统计、总结等）。'
              '你应该充分利用工具来获取信息。')

    # MCP 工具配置
    tools = [{
        "mcpServers": {
            "txt-counter": {
                "command": "python",
                "args": ["txt_counter.py"],
            }
        }
    }]

    # 创建助手实例
    bot = Assistant(
        llm=llm_cfg,
        name='桌面文件助手',
        description='可以帮你读取和分析桌面TXT文件的智能助手',
        system_message=system,
        function_list=tools,
    )
    return bot

def app_gui():
    """图形界面模式"""
    try:
        print("正在启动 Web 界面...")
        bot = init_agent_service()
        
        # 配置界面预设问题
        chatbot_config = {
            'prompt.suggestions': [
                '桌面上现在的 .txt 文件有几个？',
                '列出桌面所有的 txt 文件名',
                '读取 test.txt 的内容并帮我统计字数',
                '分析一下 notes.txt 里的主要内容'
            ]
        }

        WebUI(
            bot,
            chatbot_config=chatbot_config
        ).run()
    except Exception as e:
        print(f"启动失败: {str(e)}")

if __name__ == '__main__':
    app_gui()

---

💻 运行效果展示

1. 启动服务

在终端设置好环境变量（或者直接在代码里填入 Key），运行 bot 脚本：

set DASHSCOPE_API_KEY=sk-xxxxxxxxxxxx  # Windows CMD
export DASHSCOPE_API_KEY=sk-xxxxxxxxxxxx # Linux/Mac
python assistant_mcp_txt_bot.py

2. Web UI 交互

打开浏览器访问 http://127.0.0.1:7860。

场景一：查询文件列表

用户输入："看看我桌面上有什么 txt 文件？"

Agent 会自动调用 list_desktop_txt_files 工具。

场景二：读取并分析内容

用户输入："读取 888txt 的内容，并告诉我它讲了什么，有多少个字符？"

Agent 会先调用 read_txt_file 获取内容，然后利用 qwen-max 的能力进行总结和计数。

---

🔍 技术原理解析

整个流程的数据流向如下：

1. 用户 在 WebUI 发出自然语言指令（例如："统计 test.txt 字数"）。
2. Qwen-Agent 接收指令，将 Prompt 发送给 Qwen-Max 模型。
3. 模型 判断需要使用工具，返回 Function Call 指令（read_txt_file）。
4. Qwen-Agent 通过 stdio 管道向 txt_counter.py 发送 JSON-RPC 请求。
5. MCP Server (txt_counter.py) 执行本地文件读取操作，返回文件内容。
6. Qwen-Agent 将文件内容再次投喂给 Qwen-Max。
7. 模型 根据文件内容生成最终的统计结果和回答。

---

📝 总结

通过这个简单的 Demo，我们展示了 MCP (Model Context Protocol) 的强大之处。开发者无需将所有逻辑都塞进 Agent 内部，而是通过标准化的协议，将本地文件系统、数据库、API 等资源封装成独立的 MCP Server。

Qwen-Agent 对此提供了极佳的支持，使得"大模型"与"本地世界"的连接变得前所未有的简单。