新手也能开发MCP服务：从0写代码到客户端调用，全流程+避坑指南

注：此文章内容均节选自充电了么创始人，CEO兼CTO陈敬雷老师的新书《GPT多模态大模型与AI Agent智能体》（跟我一起学人工智能）【陈敬雷编著】【清华大学出版社】

清华《GPT多模态大模型与AI Agent智能体》书籍配套视频课程【陈敬雷】

文章目录

• GPT多模态大模型与AI Agent智能体系列八十九
• • 新手也能开发MCP服务：从0写代码到客户端调用，全流程+避坑指南
  • • • 一、先搞懂：MCP到底能解决什么问题？
      • 二、5分钟开发MCP服务：从环境准备到代码实现
      • • 1. 环境准备：3步搭好开发基础
        • 2. 核心开发：定义你的“大模型可用工具”
        • • （1）定义工具函数（Tools）：让大模型能“执行操作”
          • （2）定义资源（Resources）：让大模型能“读取数据”
          • （3）定义提示词模板（Prompts）：让大模型“按模板对话”
          • （4）启动服务：选对传输协议很重要
      • 三、客户端配置：让大模型“找到并调用你的服务”
      • • 1. 配置服务路径
        • 2. 测试调用：用自然语言触发服务
        • 3. 可视化调试：用MCP Inspector查问题
      • 四、高级玩法：让你的MCP服务更实用
      • • 1. 安全性控制：避免工具“越权操作”
        • 2. 集成现有API：让MCP服务对接外部能力
        • 3. 动态扩展：直接复用公共MCP服务
      • 五、避坑指南：新手常踩的5个坑及解决方案
      • 六、总结：MCP是大模型落地的“必备技能”
    • 更多技术内容
• 总结

GPT多模态大模型与AI Agent智能体系列八十九

新手也能开发MCP服务：从0写代码到客户端调用，全流程+避坑指南

在大模型应用爆发的当下，一个关键痛点日益凸显：如何让AI模型轻松调用本地文件、自定义工具或外部API？Anthropic推出的MCP（Model Context Protocol，模型上下文协议）给出了答案——它像一套“通用接口标准”，让大模型与外部资源的协作从“定制化开发”变成“即插即用”。

本文基于Python技术栈，以“5分钟快速开发”为核心，手把手拆解MCP服务的开发全流程。无论你是AI新手还是想快速落地工具集成的开发者，都能跟着步骤从0实现一个能被大模型调用的MCP服务，还能避开90%的入门坑。

一、先搞懂：MCP到底能解决什么问题？

简单说，MCP是大模型与外部世界的“翻译官”。没有MCP时，让大模型调用本地文件、计算器或企业API，需要针对不同模型写不同接口，耗时且兼容性差；有了MCP后，只需按统一规则开发一次服务，Claude、Cursor、CLINE等主流工具都能识别调用。

它的核心价值体现在：

• 标准化协作：统一大模型与工具的交互规则，避免“一个模型一套接口”的重复劳动；
• 低门槛扩展：新手也能开发自定义服务，让大模型拥有调用本地文件、执行特定函数的能力；
• 跨场景适配：支持本地通信（如IDE内调用）和远程协作（跨设备调用服务），覆盖个人与企业场景。

二、5分钟开发MCP服务：从环境准备到代码实现

1. 环境准备：3步搭好开发基础

MCP开发依赖Python环境和官方SDK，新手按以下步骤操作，5分钟内即可就绪：

• Step 1：安装Python（≥3.10） MCP对Python版本有要求（推荐3.10及以上），确保环境达标。可通过python –version检查版本，若不满足，官网下载对应版本即可。

• Step 2：用虚拟环境隔离依赖（推荐） 为避免依赖冲突，建议创建专用虚拟环境：

  # 创建虚拟环境
  python -m venv mcp-env
  # 激活环境（Linux/Mac）
  source mcp-env/bin/activate
  # 激活环境（Windows）
  mcp-env\\Scripts\\activate

• Step 3：安装MCP SDK 官方提供的SDK已封装核心功能，一行命令即可安装：

  pip install mcp

  安装完成后，运行mcp version，若返回版本号（如1.5.0），说明环境准备就绪。

• 选对开发工具 开发阶段可直接用记事本或VS Code写代码；测试阶段需用支持MCP的客户端（如CLINE、Cursor、Claude Desktop），也可搭配官方调试工具MCP Inspector。

2. 核心开发：定义你的“大模型可用工具”

MCP服务的核心是向大模型暴露“可调用的能力”，主要通过三大“协议原语”实现：Tools（工具函数）、Resources（资源）、Prompts（提示词模板）。以下用实例逐个拆解。

（1）定义工具函数（Tools）：让大模型能“执行操作”

工具函数是MCP服务的“核心功能体”，比如“获取桌面文件列表”“生成问候语”等，大模型可通过自然语言调用这些函数并获取结果。

示例代码（custom_mcp.py）：

# 从官方SDK导入FastMCP
from mcp.server.fastmcp import FastMCP
import os

# 创建MCP实例（可自定义名称）
mcp = FastMCP()

# 定义“获取桌面文件列表”工具（仅支持macOS）
@mcp.tool() # 用装饰器标记为工具
def list_desktop_files() –> list:
"""获取当前用户桌面上的所有文件列表（macOS专属实现）"""
# 拼接桌面路径（macOS用户桌面路径固定为"~/Desktop"）
desktop_path = os.path.expanduser("~/Desktop")
# 返回文件列表（需为JSON兼容类型：列表、字符串、字典等）
return os.listdir(desktop_path)

# 定义“生成双语问候语”工具
@mcp.tool()
def say_hello(name: str) –> str:
"""生成个性化问候语（中英双语版）"""
return f"🎉 你好 {name}! (Hello {name}!)"

关键细节：

• 工具函数需用@mcp.tool()装饰器标记，大模型会通过文档字符串（函数注释）理解其功能；
• 返回值必须是JSON可序列化类型（如列表、字符串、字典），否则大模型无法解析；
• 参数类型需明确（如name: str），帮助大模型正确传参。

（2）定义资源（Resources）：让大模型能“读取数据”

资源是静态或动态的数据块（如配置信息、数据库查询结果），大模型可通过类似“URL”的路径调用。

示例代码（接上面的custom_mcp.py）：

@mcp.resource("config://app_settings") # 定义资源路由（类似URL）
def get_app_config() –> dict:
"""返回应用的基础配置信息"""
return {"theme": "dark", "language": "zh-CN"}

后续大模型输入“获取app设置”，会自动调用config://app_settings资源，返回配置字典。

（3）定义提示词模板（Prompts）：让大模型“按模板对话”

提示词模板是预设的交互流程，能让大模型按固定格式处理任务（如代码审查、内容生成）。

示例代码（接上面的custom_mcp.py）：

@mcp.prompt() # 标记为提示词模板
def code_review_prompt(code: str) –> str:
"""生成代码审查的提示词模板"""
return f"请审查以下代码并指出问题：\\n\\n{code}"

当大模型需要审查代码时，会自动套用这个模板，确保输出格式统一。

（4）启动服务：选对传输协议很重要

开发完功能后，需通过mcp.run()启动服务，关键是选对“传输协议”——它决定了服务如何与大模型通信：

• stdio协议：通过标准输入/输出通信，适合本地开发（如IDE内调用），简单无需配置；
• sse协议：基于HTTP事件流，适合远程调用（跨设备协作），需部署为Web服务。

新手入门推荐先用水印stdio协议，完整启动代码如下（接上面的custom_mcp.py）：

if __name__ == "__main__":
mcp.run(transport='stdio') # 启用stdio传输，本地调试更方便

三、客户端配置：让大模型“找到并调用你的服务”

服务开发完成后，需在客户端（如CLINE）中配置，让大模型能识别并调用。以CLINE为例，步骤如下：

1. 配置服务路径

在CLINE中找到“MCP设置”，添加服务配置文件（如cline_mcp_settings.json），格式如下：

{
"mcpServers": {
"my_first_mcp_service": { // 服务名称（自定义，需唯一）
"command": "python3", // 启动命令（用python3运行代码）
"args": [
"/Users/你的用户名/代码路径/custom_mcp.py" // 代码文件的绝对路径
]
}
}
}

配置时注意：路径需用绝对路径，Windows系统需用双斜杠（\\\\）；命令需与环境匹配（如Windows用python，Mac/Linux用python3）。

2. 测试调用：用自然语言触发服务

配置完成后，刷新CLINE客户端，向大模型发送指令即可调用服务：

• 输入“我的桌面有哪些文件”，会触发list_desktop_files工具，返回桌面文件列表；
• 输入“问候用户小明”，会调用say_hello工具，返回“🎉 你好 小明! (Hello 小明!)”；
• 输入“获取app设置”，会返回config://app_settings资源定义的配置信息。

3. 可视化调试：用MCP Inspector查问题

若调用失败（如工具未识别、返回错误），可用官方调试工具MCP Inspector排查：

四、高级玩法：让你的MCP服务更实用

掌握基础开发后，这些技巧能让服务更适配实际场景：

1. 安全性控制：避免工具“越权操作”

自定义工具可能涉及本地文件或系统操作，需限制权限：

• 比如list_desktop_files工具，仅允许访问~/Desktop路径，不扩展到其他目录；
• 敏感操作（如数据库查询）可通过Nacos等工具管理密钥，避免硬编码在代码中。

2. 集成现有API：让MCP服务对接外部能力

无需重写代码，可通过“协议转换”让MCP服务调用现有HTTP API。例如，将高德地图API封装为MCP服务：

3. 动态扩展：直接复用公共MCP服务

不想自己开发？可通过MCP市场（如AIbase、mcp.so）获取现成服务：

• 市场中有大量官方或第三方开发的MCP服务（如计算器、翻译、格式转换）；
• 在客户端中直接添加服务地址，无需代码即可调用，实现“零开发集成”。

五、避坑指南：新手常踩的5个坑及解决方案

六、总结：MCP是大模型落地的“必备技能”

从本质上看，MCP的价值不仅是“标准化协议”，更是降低AI工具集成门槛的“普惠技术”。哪怕你只会写简单的Python函数，也能通过它让大模型拥有调用本地文件、自定义工具的能力——比如让AI自动整理桌面文件、按模板生成报告，甚至对接企业内部系统。

跟着本文的步骤，你已掌握从“环境准备→代码开发→客户端调用→调试优化”的全流程。下一步，不妨从一个简单需求（如“让大模型调用计算器”）开始实践，逐步扩展到更复杂的场景。在AI应用落地的浪潮中，能让大模型“动手干活”的能力，会成为你不可替代的竞争力。

更多技术内容

更多技术内容可参见 清华《GPT多模态大模型与AI Agent智能体》书籍配套视频【陈敬雷】。 更多的技术交流和探讨也欢迎加我个人微信chenjinglei66。

总结

此文章有对应的配套新书教材和视频：

【配套新书教材】 《GPT多模态大模型与AI Agent智能体》（跟我一起学人工智能）【陈敬雷编著】【清华大学出版社】 新书特色：《GPT多模态大模型与AI Agent智能体》（跟我一起学人工智能）是一本2025年清华大学出版社出版的图书，作者是陈敬雷，本书深入探讨了GPT多模态大模型与AI Agent智能体的技术原理及其在企业中的应用落地。 全书共8章，从大模型技术原理切入，逐步深入大模型训练及微调，还介绍了众多国内外主流大模型。LangChain技术、RAG检索增强生成、多模态大模型等均有深入讲解。对AI Agent智能体，从定义、原理到主流框架也都进行了深入讲解。在企业应用落地方面，本书提供了丰富的案例分析，如基于大模型的对话式推荐系统、多模态搜索、NL2SQL数据即席查询、智能客服对话机器人、多模态数字人，以及多模态具身智能等。这些案例不仅展示了大模型技术的实际应用，也为读者提供了宝贵的实践经验。 本书适合对大模型、多模态技术及AI Agent感兴趣的读者阅读，也特别适合作为高等院校本科生和研究生的教材或参考书。书中内容丰富、系统，既有理论知识的深入讲解，也有大量的实践案例和代码示例，能够帮助学生在掌握理论知识的同时，培养实际操作能力和解决问题的能力。通过阅读本书，读者将能够更好地理解大模型技术的前沿发展，并将其应用于实际工作中，推动人工智能技术的进步和创新。

【配套视频】

清华《GPT多模态大模型与AI Agent智能体》书籍配套视频【陈敬雷】 视频特色： 前沿技术深度解析，把握行业脉搏

实战驱动，掌握大模型开发全流程

智能涌现与 AGI 前瞻，抢占技术高地

上一篇：《GPT多模态大模型与AI Agent智能体》系列一》大模型技术原理 – 大模型技术的起源、思想 下一篇：DeepSeek大模型技术系列五》DeepSeek大模型基础设施全解析：支撑万亿参数模型的幕后英雄