1. 项目概述当本地大模型学会“打电话”最近在折腾本地大模型的朋友估计都遇到过同一个痛点模型能力再强也像一座信息孤岛。你问它今天的天气它只能根据训练数据里的“常识”瞎猜你想让它帮你查一下快递物流它更是无能为力。我们费劲部署了Qwen2.5这样优秀的开源模型难道就只能让它做个“离线版百科全书”吗当然不是。这个项目的核心目标就是给本地运行的Qwen2.5大模型装上“手和脚”让它能够主动调用我们自己的、或者外部的API服务。比如你可以让它连接你的智能家居API来开关灯调用公司的内部数据接口生成业务报表或者整合公开的天气、新闻API来获取实时信息。这背后的关键技术就是MCPModel Context Protocol协议。你可以把它理解为大模型世界的“通用电话线”和“电话簿”标准。过去每个AI应用想给大模型扩展能力都得自己从头造一套通信轮子既麻烦又不通用。MCP协议的出现就是为了标准化大模型与外部工具我们称之为“服务器”之间的对话方式。简单来说这个项目就是搭建一个环境在你的电脑上用Ollama运行Qwen2.5作为“大脑”客户端同时启动一个或多个遵循MCP协议的“工具服务器”比如一个能查询数据库的服务器一个能发邮件的服务器。然后通过一个支持MCP的AI应用框架如Claude Desktop、Cursor等作为“调度中心”让Qwen2.5能够根据你的指令自动选择并调用合适的工具服务器来完成任务。最终实现的效果是你对AI说“帮我查一下仓库里A产品的库存并邮件通知销售经理”它就能自动完成“查数据库API”和“调用邮件发送API”这一系列操作。这非常适合那些注重数据隐私、希望低成本拥有定制化AI助理的开发者、技术爱好者和中小企业。你不必再将敏感数据上传到云端也不必为昂贵的闭源模型API调用次数付费完全在本地可控的环境中构建一个真正“听得懂人话、办得成实事”的智能助手。2. 核心架构与MCP协议深度解析2.1 为什么是MCP协议选型的背后逻辑在让大模型调用外部能力这条路上业界有过不少尝试。早期常见的是通过Function Calling函数调用或Tool Calling工具调用让模型输出一个结构化的JSON然后由应用后端解析这个JSON再去执行对应的函数。这种方式耦合度高每增加一个新工具都需要修改后端的代码和模型的提示词。后来出现了像LangChain这样的框架它定义了一套Tools的抽象方便集成但其通信方式依然是框架自定义的不同框架之间的工具无法直接互通。而MCP协议的目标就是解决这个“互通”问题。它由Anthropic公司牵头设计是一个开放标准核心思想是将工具的定义、发现和调用过程标准化。选择MCP协议来构建这个项目主要基于以下几点考量标准化与未来兼容性MCP是一个正在快速发展的开放协议得到了Claude Desktop、Cursor、Windsurf等主流AI IDE的支持。采用它意味着你构建的工具服务器未来可以无缝接入更多支持MCP的客户端而不必为每个客户端重写适配层。解耦与灵活性在MCP架构中大模型客户端如Claude Desktop、模型本身Qwen2.5和工具服务器是三者分离的。你可以独立升级或更换其中任何一个组件。例如今天用Qwen2.5明天可以换成DeepSeek只要它们都通过同一个MCP客户端来调度工具服务器完全不用变。开发体验友好MCP协议基于JSON-RPC 2.0通信方式清晰。社区已经提供了Python、JavaScript/TypeScript、Go等多种语言的SDK大大降低了开发一个合规工具服务器的门槛。你只需要关注工具本身的业务逻辑。动态工具发现这是MCP的一大亮点。工具服务器启动后会主动向客户端“注册”自己提供了哪些工具包括工具名称、描述、参数schema。客户端进而告知大模型可以动态地获知当前可用的全部工具列表无需预先写死在配置里。你随时可以启停一个工具服务器整个系统的能力列表会自动更新。2.2 项目整体技术栈与工作流为了清晰地实现“本地Qwen2.5通过MCP调用私有API”我们需要搭建一个微型的、本地的“AI智能体”生态系统。下图展示了核心组件及其交互关系[用户] | v [支持MCP的AI客户端] (如Claude Desktop, Cursor) | (通过stdin/stdout或SSE传输MCP协议消息) v [Ollama Qwen2.5模型] (作为“大脑”理解指令并决定调用哪个工具) | v (模型思考后通过客户端返回工具调用请求) [支持MCP的AI客户端] | (根据工具名将请求路由到对应的工具服务器) v [自定义MCP工具服务器] (如查询API服务器、邮件服务器) | (执行具体逻辑调用真正的私有API) v [你的私有API服务] (或第三方公开API)核心组件拆解MCP客户端调度中心我们选择Claude Desktop。虽然它名字叫“Claude”但它本质上是一个支持MCP协议的通用AI应用前端。它的重要功能是作为MCP主机Host可以配置并连接多个MCP服务器即我们的工具服务器并在用户与模型对话时将可用的工具信息提供给模型并转发模型的工具调用请求。大模型推理引擎使用Ollama。它是在本地运行和管理大模型最简便的工具之一完美支持Qwen2.5系列模型。我们将配置Claude Desktop使用本地Ollama服务提供的Qwen2.5模型。MCP工具服务器核心开发部分这是本项目需要动手实现的关键。我们将使用官方提供的modelcontextprotocol/sdkTypeScript/JavaScript版或mcpPython版来快速开发一个或多个服务器。每个服务器可以封装一个或多个“工具”每个工具对应一个我们希望模型调用的能力例如get_weather、query_database、send_email。私有API服务这是你已有的或将要开发的后端服务。MCP工具服务器在收到调用请求后内部会去调用这些真正的API获取结果然后按照MCP协议格式返回给客户端和模型。整个工作流的触发始于用户在Claude Desktop里输入一句话。Claude Desktop会将这句话连同当前已注册的所有工具的描述一起发送给Ollama中的Qwen2.5。Qwen2.5理解后如果判断需要调用工具就会输出一个结构化的工具调用请求。Claude Desktop捕获这个请求找到对应的工具服务器执行拿到结果后再送回给Qwen2.5由Qwen2.5整合结果并生成最终的自然语言回复给用户。这个过程对用户是透明的感觉就像在和一个无所不能的AI对话。3. 环境准备与核心组件部署3.1 基础环境搭建Ollama与Qwen2.5第一步是让我们的“大脑”运转起来。Ollama的安装极其简单访问其官网下载对应操作系统的安装包即可。安装完成后打开终端拉取Qwen2.5模型。这里我推荐从较小的版本开始尝试比如7B参数量的版本对硬件更友好。# 拉取 Qwen2.5-7B 模型 (指令微调版本更适合对话和工具调用) ollama pull qwen2.5:7b拉取完成后你可以直接运行ollama run qwen2.5:7b在命令行交互测试确保模型加载正常。但我们的目标不是命令行交互而是让Ollama作为一个后台服务供Claude Desktop调用。Ollama默认会在http://localhost:11434提供一个API服务保持它运行即可。注意首次运行较大的模型如14B、32B时请确保你的电脑有足够的RAM和显存。7B模型在16GB内存的机器上通常可以流畅运行。如果遇到加载缓慢或崩溃可以在Ollama的Modelfile中尝试使用-ngl参数将部分层卸载到GPU或者直接换用更小的qwen2.5:0.5b或qwen2.5:1.5b模型进行功能验证。3.2 MCP客户端配置以Claude Desktop为例Claude Desktop是当前体验MCP生态最方便的工具。安装后我们需要对其进行配置使其连接本地Ollama和我们的工具服务器。Claude Desktop的配置文件通常位于macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json如果文件不存在可以手动创建。一个最基础的、连接本地Ollama的配置如下{ defaultModel: ollama/qwen2.5:7b, ollama: { baseUrl: http://localhost:11434, model: qwen2.5:7b } }这个配置告诉Claude Desktop使用本地Ollama服务并指定模型。但这还不够我们需要让它知道MCP工具服务器的存在。配置MCP服务器有两种主要方式通过配置文件静态添加或通过Claude Desktop的UI动态添加较新版本支持。这里展示静态配置方式更为稳定可靠。假设我们即将开发一个名为my-tools-server的工具服务器它通过标准输入输出stdio与Claude Desktop通信那么配置需要扩展{ defaultModel: ollama/qwen2.5:7b, ollama: { baseUrl: http://localhost:11434, model: qwen2.5:7b }, mcpServers: { my-tools-server: { command: node, args: [/ABSOLUTE/PATH/TO/YOUR/mcp-server/index.js], env: { API_KEY: your_private_api_key_here } } } }关键参数解析command: 启动工具服务器的命令这里是node。args: 命令的参数即我们工具服务器主文件的路径。务必使用绝对路径相对路径很可能导致启动失败。env: 传递给工具服务器的环境变量。这是向工具服务器传递私有API密钥、数据库连接字符串等敏感信息的推荐方式避免硬编码在代码中。配置完成后重启Claude Desktop它就会在启动时自动运行我们指定的命令来启动MCP工具服务器并与之建立连接。3.3 开发你的第一个MCP工具服务器现在进入核心开发环节。我们将使用Node.js和官方SDK来创建一个最简单的工具服务器它提供一个查询系统时间的工具。首先初始化项目并安装依赖mkdir my-mcp-server cd my-mcp-server npm init -y npm install modelcontextprotocol/sdk然后创建入口文件index.jsconst { Server } require(modelcontextprotocol/sdk/server/index.js); const { StdioServerTransport } require(modelcontextprotocol/sdk/server/stdio.js); // 1. 创建Server实例并声明名称和版本 const server new Server( { name: my-tools-server, version: 1.0.0, }, { capabilities: { tools: {}, // 声明本服务器提供工具 }, } ); // 2. 定义工具获取当前时间 server.setRequestHandler(tools/list, async () { return { tools: [ { name: get_current_time, description: 获取当前的系统日期和时间。, inputSchema: { type: object, properties: { // 这个工具不需要输入参数 }, required: [], }, }, ], }; }); // 3. 处理工具调用请求 server.setRequestHandler(tools/call, async (request) { const { name, arguments: args } request.params; if (name get_current_time) { const now new Date(); const timeString now.toLocaleString(zh-CN, { timeZone: Asia/Shanghai, hour12: false }); return { content: [ { type: text, text: 当前系统时间是${timeString}, }, ], }; } // 如果收到未知的工具调用请求抛出错误 throw new Error(未知的工具: ${name}); }); // 4. 启动服务器使用stdio传输层与Claude Desktop通信 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP工具服务器已启动等待连接...); } main().catch((error) { console.error(服务器启动失败:, error); process.exit(1); });代码要点与避坑指南传输层Transport我们使用了StdioServerTransport这是与像Claude Desktop这类桌面应用集成的最常见方式通过标准输入输出流交换数据。如果你的工具服务器是独立的HTTP服务则需要使用其他的Transport。工具定义在tools/list处理器中返回的工具列表其description字段至关重要。大模型Qwen2.5正是根据这个描述来判断在什么场景下该调用哪个工具。描述应清晰、简洁说明工具的用途和输入参数。错误处理在tools/call处理器中务必对未知的工具名进行处理。虽然理论上客户端只会请求已列出的工具但良好的错误处理能增加服务器的健壮性。日志输出使用console.error输出日志信息因为console.log的输出会被作为协议消息的一部分发送给客户端导致通信混乱。console.error的内容会输出到宿主进程Claude Desktop的标准错误流方便调试。编写完成后记得将Claude Desktop配置文件中的args路径修改为这个index.js的绝对路径。重启Claude Desktop如果配置正确你将在Claude Desktop的界面中通常在新会话开始时看到提示表明已连接到自定义工具。你可以尝试问Qwen2.5“现在几点了”观察它是否会调用get_current_time工具并返回正确结果。4. 实战封装私有API为MCP工具一个只会报时的助手显然不够。接下来我们实战封装一个调用私有天气查询API的工具。假设你公司内部有一个天气服务API端点为http://internal-api.example.com/weather需要API密钥认证接收城市名作为参数返回JSON格式的天气数据。4.1 设计工具与处理认证首先规划我们的工具。我们将创建一个名为get_internal_weather的工具。考虑到安全性API密钥不应写在代码里。如前所述我们通过Claude Desktop配置文件的env字段传入。更新index.js在工具列表中添加新工具server.setRequestHandler(tools/list, async () { return { tools: [ { name: get_current_time, description: 获取当前的系统日期和时间。, inputSchema: { type: object, properties: {}, required: [], }, }, { name: get_internal_weather, description: 根据城市名称查询内部的天气信息包括温度、天气状况和湿度。, inputSchema: { type: object, properties: { city: { type: string, description: 要查询天气的城市名称例如“北京”、“上海”。, }, }, required: [city], // 标记city为必填参数 }, }, ], }; });4.2 实现API调用与错误处理接下来实现这个工具的调用处理器。我们需要使用node-fetch或axios等库来发起HTTP请求。这里以node-fetch为例首先安装npm install node-fetch。然后在文件顶部引入并编写处理逻辑const fetch (...args) import(node-fetch).then(({default: fetch}) fetch(...args)); // ... 之前的 server.setRequestHandler(tools/list, ...) 部分保持不变 server.setRequestHandler(tools/call, async (request) { const { name, arguments: args {} } request.params; // 注意 arguments 是关键字这里解构重命名 if (name get_current_time) { // ... 之前的实现 } if (name get_internal_weather) { const { city } args; if (!city) { throw new Error(必须提供城市名称参数。); } // 从环境变量获取API密钥 const apiKey process.env.INTERNAL_WEATHER_API_KEY; if (!apiKey) { throw new Error(服务器未配置天气API密钥。); } const apiUrl http://internal-api.example.com/weather?city${encodeURIComponent(city)}; try { const response await fetch(apiUrl, { method: GET, headers: { Authorization: Bearer ${apiKey}, Content-Type: application/json, }, }); if (!response.ok) { // 处理HTTP错误例如401未授权404未找到500服务器错误等 const errorText await response.text(); throw new Error(天气API请求失败 (${response.status}): ${errorText}); } const weatherData await response.json(); // 假设返回的JSON结构为 { temperature: 22, condition: 晴, humidity: 65 } const { temperature, condition, humidity } weatherData; return { content: [ { type: text, text: 城市【${city}】的天气情况温度 ${temperature}°C天气 ${condition}湿度 ${humidity}%。, }, // 你也可以返回结构化数据供客户端进一步渲染 { type: resource, resource: { text: JSON.stringify(weatherData, null, 2), mimeType: application/json, }, } ], }; } catch (error) { // 捕获网络错误或JSON解析错误 console.error(调用天气API出错:, error); throw new Error(查询天气时发生错误${error.message}); } } throw new Error(未知的工具: ${name}); });4.3 更新配置与测试现在需要更新Claude Desktop的配置文件将API密钥通过环境变量传入{ defaultModel: ollama/qwen2.5:7b, ollama: { baseUrl: http://localhost:11434, model: qwen2.5:7b }, mcpServers: { my-tools-server: { command: node, args: [/ABSOLUTE/PATH/TO/YOUR/my-mcp-server/index.js], env: { INTERNAL_WEATHER_API_KEY: your_secret_weather_api_key_here } } } }重启Claude Desktop。重启后新的工具应该已被注册。现在你可以尝试向Qwen2.5提问“上海天气怎么样”。观察与调试Qwen2.5应该能理解你的意图并决定调用get_internal_weather工具参数为{“city”: “上海”}。Claude Desktop会将此调用请求转发给你的工具服务器。工具服务器执行HTTP请求获取结果后返回。Claude Desktop将结果返回给Qwen2.5。Qwen2.5将原始的天气数据整合成一段通顺的回复呈现给你。如果过程中出现错误首先检查Claude Desktop的日志通常可以在其设置中打开日志文件位置查看是否有服务器启动失败或通信错误。其次在你的工具服务器代码中多用console.error输出关键节点的信息这些信息会出现在你启动Claude Desktop的终端或系统日志中。实操心得参数验证与模型引导在定义工具时inputSchema的description字段不仅给人看更是给模型看的。清晰的描述能极大提高模型调用工具的准确性。例如如果你有一个查询员工信息的工具参数是employee_id描述写成“员工的唯一标识符格式为‘E’后接5位数字例如 E12345”会比单纯写“员工ID”效果更好。模型在生成调用参数时会参考这些描述来约束格式。5. 高级技巧与性能优化5.1 处理复杂参数与上下文记忆现实中的API参数往往更复杂。MCP协议支持完整的JSON Schema来定义参数包括嵌套对象、数组、枚举类型等。例如一个创建工单的工具{ name: create_ticket, description: 在内部系统中创建一个新的支持工单。, inputSchema: { type: object, properties: { title: { type: string, description: 工单的简要标题。, }, description: { type: string, description: 工单的详细描述。, }, priority: { type: string, description: 工单优先级。, enum: [low, medium, high, critical], default: medium, }, tags: { type: array, description: 与工单相关的标签。, items: { type: string }, }, assignee: { type: object, description: 指定处理人信息。, properties: { id: { type: string }, name: { type: string }, }, required: [id], }, }, required: [title, description], }, }对于需要上下文的多轮对话场景例如用户说“用刚才提到的那个项目号查一下状态”标准的MCP工具调用本身是无状态的。状态管理需要依靠客户端如Claude Desktop和模型Qwen2.5的能力。客户端会在对话历史中提供上下文模型需要从中提取关键信息如“刚才提到的项目号”来填充工具参数。这考验的是模型的理解能力。为了辅助模型我们可以在工具描述中提示用户提供完整信息或者在服务器端实现一些简单的会话缓存逻辑但这会破坏服务器的无状态性需谨慎设计。5.2 多工具服务器管理与资源Resources探索一个复杂的助手可能需要几十个工具。把所有工具都写在一个服务器里会让代码变得臃肿。更好的做法是按领域拆分多个MCP服务器。例如一个finance-tools-server处理财务相关API一个hr-tools-server处理人力资源API。在Claude Desktop配置文件中你可以在mcpServers下并列配置多个服务器。mcpServers: { weather-tools: { ... }, finance-tools: { ... }, hr-tools: { ... } }MCP协议除了Tools还有一个强大的概念叫Resources。Tools代表“动作”可执行的操作而Resources代表“信息”可读取的上下文。例如你可以创建一个Resources服务器提供“当前用户待办事项列表”或“公司知识库文档”作为资源。当用户提问时客户端可以先将相关的资源内容作为背景信息提供给模型然后再让模型思考回答或调用工具。这类似于给模型提供了一个“实时参考资料库”。对于Qwen2.5这类本地模型合理利用Resources可以有效扩展其知识边界弥补训练数据滞后的缺点。5.3 性能调优与常见错误排查性能方面模型响应速度Qwen2.5在Ollama上的推理速度取决于你的硬件。如果感觉慢可以尝试Ollama的-ngl参数将更多层加载到GPU如果有N卡或使用量化版本更小的模型如qwen2.5:7b-instruct-q4_K_M。工具服务器响应确保你的工具服务器逻辑高效特别是调用外部API时要设置合理的超时timeout避免因为一个慢接口阻塞整个对话。可以在fetch请求中配置signal: AbortSignal.timeout(5000)来实现5秒超时。上下文长度Qwen2.5有固定的上下文窗口如7B模型通常是32K tokens。如果对话历史包含工具调用和返回的长结果过长会导致最早的记忆被遗忘也可能触发maximum context length错误。在Claude Desktop等客户端中通常有策略自动修剪或总结长历史。对于返回大量数据的工具可以考虑让工具服务器对结果进行摘要后再返回。常见错误与排查错误现象可能原因排查步骤Claude Desktop启动时报错提示无法连接MCP服务器1. 配置文件路径错误。2. Node命令或脚本路径错误。3. 工具服务器代码有语法错误启动即崩溃。1. 检查配置文件JSON格式是否正确。2. 在终端手动运行配置中的command和args看能否启动服务器。3. 查看Claude Desktop的详细日志文件。工具列表不显示或对话中模型不调用工具1. 工具服务器未成功注册。2. 工具描述不够清晰模型无法理解何时调用。3. 模型本身“工具调用”能力较弱。1. 在Claude Desktop新会话开始时查看连接状态提示。2. 优化工具名称和描述使其更贴近自然语言。3. 尝试在用户提问时更明确地指示如“请使用get_weather工具查询”。4. 换用更新或指令跟踪能力更强的模型版本。工具调用返回400或429等API错误1. 参数格式不符合私有API要求。2. API密钥无效或权限不足。3. 达到API调用频率限制。1. 在工具服务器代码中添加详细的请求和响应日志。2. 使用curl或Postman直接测试你的私有API确认其正常工作。3. 检查环境变量是否正确注入。模型输出混乱夹杂着工具调用JSON和正常文本这是正常现象。模型在“思考”时可能会在内部推理过程中输出一些结构化文本。Claude Desktop这样的客户端会负责解析只将最终的自然语言结果展示给用户。如果直接使用原始API可能需要自己处理这些中间输出。确保你使用的是像Claude Desktop这样完整支持MCP协议的客户端它负责处理与模型的复杂交互。遇到maximum context length is ... tokens错误对话历史包含多次工具调用和长响应超出了模型的最大上下文长度。1. 客户端应自动管理上下文。如果频繁出现考虑使用上下文更长的模型如72B版本如果硬件允许。2. 优化工具返回内容尽量简洁。3. 在客户端设置中减少保留的历史消息轮数。一个关键的避坑技巧环境变量与路径在开发MCP工具服务器时路径和环境变量是两大“杀手”。务必在配置中使用绝对路径。对于环境变量不仅在Claude Desktop配置中设置也要确保你的工具服务器代码能正确读取通过process.env.YOUR_KEY。在Mac/Linux上注意配置文件路径的大小写和隐藏文件夹。在Windows上注意路径中的反斜杠需要转义或使用正斜杠。最稳妥的方式是先在终端里cd到你的服务器目录用node index.js手动运行确保它能独立启动且不报错再将其配置到Claude Desktop中。
)
