简介面向AI应用开发者和智能体初学者这份PDF教程围绕MCPModel Context Protocol展开帮助读者从零掌握这一工具调用协议的核心价值与具体用法。内容先从技术体系讲起介绍MCP的来历与设计思路对比Function calling说明它如何统一客户端与服务器之间的规范、降低外部工具接入成本。随后进入实战环节讲解uv依赖管理工具的使用手把手演示MCP客户端项目创建、基础代码编写与运行并分别展示接入OpenAI、DeepSeek在线模型和本地ollama、vLLM模型的过程。后半部分以天气查询为案例完整串联服务器Server创建、客户端Client编写、通讯测试以及MCP Inspector调试最后补充进阶功能帮助读者举一反三。资源共1个PDF文件压缩包大小47.66MB内容浓缩且按章节递进适合边读边练。目前已有1124人学习浏览是对MCP既有概念梳理又有代码实操的快速上手资料。1. MCP 是什么一次把外部工具调用做成标准协议的技术变革这两年做 Agent最别扭的事不是模型选型而是让大模型学会“用工具”。以前接一个天气查询功能我得先写上百行外部函数再手写一份 JSON Schema 说清楚参数是什么最后还得调提示词模板模型才偶尔答对。MCPModel Context Protocol模型上下文协议是某 AI 实验室去年底提出的开放协议把“外部工具”统一成 MCP Server、把大模型运行环境统一成 MCP Client双方按同一套规范对话。这样一来社区里任何人开发好的工具服务器别的项目几行代码就能接入Agent 开发的门槛被明显拉低。这份《从零到一 MCP 快速入门实战》正好覆盖了从协议原理、客户端 Client 开发、接入在线与本地模型到天气查询 Server 联调的完整链路适合刚接触 Agent、想把工具接进大模型但不想从零啃协议的开发者。下面按我实际拆解的顺序把能直接复现的部分展开说。2. MCP 协议设计从 Function calling 的成本账看 Client/Server 架构2.1 Function calling 的隐性成本为什么大模型自己调不动外部工具大模型本质上是“文本生成器”训练目标是从上下文预测下一个 token。这意味着它没有任何与环境交互的能力发不了 HTTP 请求读不了本地数据库更操作不了命令行。要让大模型查询天气必须有一个中间人外部函数。大模型输出一段结构化指令代码解析后去执行真正的工具调用再把结果塞回上下文模型基于结果生成最终回复。这套机制就是 Function calling也是目前主流在线模型都支持的能力。但真正写过的人知道成本全在看不见的地方。首先是函数本身一个简单的 get_weather 要处理参数校验、异常返回、超时重试写下来七八十行很常见。其次是 JSON Schema为了让模型知道“这个函数有哪些参数、参数什么类型”每个函数都要配一份 Schema手写和维护都是体力活。更玄学的是提示词模板——同一个函数措辞稍微变一下模型返回的 tool_calls 格式就可能对不上导致调用失败。最后是复用问题团队 A 写好了天气函数团队 B 要用基本只能复制粘贴再改一轮换一个项目重来一遍。这套成本在单个工具上还能忍一旦 Agent 需要五六个工具工作量是线性甚至超线性增长。我在做模拟项目 X 时就是因为同时维护 SQL 查询、网页爬取、天气三个函数光 Schema 就改了四轮最后才意识到问题的根源不是函数写得不好而是缺少统一规范。2.2 MCP 的协议分层Client、Server 与通讯机制MCP 的答案很直接既然大量工具都要做“定义函数、写 Schema、描述给模型听”这件事那就把这套流程固化成协议。协议里大模型运行的环境叫 MCP Client外部工具运行的环境叫 MCP Server。Client 和 Server 之间按一套既定规范通信传输层默认支持 stdio本地进程间通信和 Streamable HTTP远程通信两种方式。通信内容上Server 只需要暴露两类核心能力工具发现和工具调用。工具发现对应 list_tools返回一个工具清单包含名称、描述、参数 Schema工具调用对应 call_tools接收工具名和参数执行后返回结果。MCP 官方 SDK 把这些细节封装成了 Python、TypeScript、Java 等语言的库开发者不用手动解析协议包几行代码就能完成一个 Server。具体到报文层MCP 基于 JSON-RPC 2.0。一次标准交互包括Client 发起 initialize 请求Server 返回协议版本和能力列表随后双方交换 initialized 通知建立会话之后 Client 发送 tools/list 请求获取工具清单当模型决定调用某个工具时Client 再发送 tools/call 请求携带工具名和参数Server 执行后返回结构化结果。SDK 把这几个步骤封装成函数但你了解底层结构对排查问题很有帮助——比如看到 EOFError 就知道是 stdio 管道断了看到 MethodNotFound 多半是两边协议版本不一致。客户端在 SDK 帮助下拿到 tools 列表后会把工具改写成模型能认识的 function 格式然后走和 Function calling 几乎一样的交互流程。区别在于工具不再是当前项目里写死的函数而是从 Server 动态发现的。换一个工具服务客户端代码不用改只需要在协议层重新握手一次。这就是“车同轨、书同文”的价值——工具服务器可以写成一次、到处复用。两者的核心差异可以用一个表说清对比项Function callingMCP工具定义位置写死在当前项目Server 独立提供工具复用复制粘贴再改协议级复用接入成本每工具上百行SDK 几行通信规范各家模型 API 不一统一 JSON-RPC 2.02.3 Agent 开发技术体系回顾MCP 补的是“工具”这一层一套完整的 Agent 技术体系一般包含四层模型层负责理解和生成记忆层负责保存上下文与长期知识工具层负责连接外部世界规划层负责拆解任务、决定调用哪个工具。大多数项目初期最纠结的是模型选型但落地时卡住的往往是工具层。模型不对可以换工具接不进去整个链路就断了。MCP 站的位置就是工具层。它不替代模型也不替代规划逻辑只是把“外部工具怎么被大模型调用”这件事标准化。现在主流编码 IDE 直接充当 MCP Client在线模型服务也陆续兼容了 MCP 协议开源社区里出现了上千个现成 Server覆盖 SQL 检索、网页抓取、命令行操作等场景。对个人开发者来说切入路径很清晰先用 MCP SDK 搭一个 Client再接一个现成 Server最后自己写 Server。这份课程里的顺序也是这样安排的客户端先行、服务器在后每个阶段都能独立验证。3. MCP 客户端开发实战uv 环境搭建与极简 CLI 从零跑通3.1 uv 工具MCP 项目为什么推荐它uv 是一个用 Rust 写的 Python 依赖管理工具定位是替代 pip、venv 和 pip-tools。相比 pip它的核心优势有三点速度更快依赖解析和安装都快一个量级自带虚拟环境管理uv venv 比 python -m venv 更轻量直接支持 pyproject.toml和现代 Python 项目的工程化习惯对齐。MCP 类项目依赖面比较杂往往同时涉及 mcp、openai、dotenv 等库用 uv 管理可以避免 pip 在不同环境里装错包的问题。常见做法是先安装 uv再在项目目录里完成虚拟环境创建和依赖安装。安装方式有两种如果机器上已经有 pip直接执行pip install uv如果没有 pip可以用官方安装脚本curl -LsSf https://astral.sh/uv/install.sh | sh安装完成后uv 的日常用法和 pip 高度相似但写法更简洁。常用的几条命令可以记一下uv 命令作用等价传统命令uv venv myenv创建虚拟环境python -m venv myenvuv pip install requests安装依赖pip install requestsuv run python script.py自动用当前环境运行python script.py这里有个细节值得注意uv venv 会自动识别当前项目主目录并创建虚拟环境不需要像 conda 那样手动指定前缀路径。后续加依赖时uv add 会把包名写进 pyproject.toml换机器时一条 uv sync 就能还原整个环境。3.2 初始化项目uv init 到 uv add mcp整个初始化过程就是四条命令按顺序执行# 创建项目目录 uv init mcp-client cd mcp-client # 创建虚拟环境 uv venv # 激活虚拟环境Linux/macOS source .venv/bin/activate # Windows 下用 .venv\Scripts\activate # 安装 MCP SDK uv add mcp逻辑说明uv init 会生成 pyproject.toml 和最小工程骨架uv venv 在项目根目录创建 .venv 环境uv add mcp 等价于 pip install mcp但会把 mcp 写入 pyproject.toml 的依赖列表。激活虚拟环境这一步新版本的 uv 其实可以用 uv run 隐式完成但显式激活对后续排查哪条命令用了哪个 Python 更直观。参数说明uv 默认创建的虚拟环境 Python 版本继承当前系统默认解释器。如果你机器上有多个 Python 版本建议在 uv venv 后面加 --python 3.11 这类参数锁定版本MCP SDK 目前对 3.10 到 3.12 支持都比较稳。3.3 编写基础客户端MCPClient 类与异步循环在项目目录创建 client.py写入以下代码import asyncio from contextlib import AsyncExitStack from mcp import ClientSession class MCPClient: def __init__(self): 初始化 MCP 客户端 self.session None self.exit_stack AsyncExitStack() async def connect_to_mock_server(self): 模拟 MCP 服务器连接暂不连接真实服务器 print(MCP 客户端已初始化但未连接到服务器) async def chat_loop(self): 运行交互式聊天循环 print(\nMCP 客户端已启动输入 quit 退出) while True: try: query input(\nQuery: ).strip() if query.lower() quit: break print(f[Mock Response] 你说的是{query}) except Exception as e: print(f发生错误: {str(e)}) async def cleanup(self): 清理资源 await self.exit_stack.aclose() async def main(): client MCPClient() try: await client.connect_to_mock_server() await client.chat_loop() finally: await client.cleanup() if __name__ __main__: asyncio.run(main())这段代码的骨架值得逐段拆开看后面接真实模型要改的就是它。import 部分做了三件事asyncio 是 Python 内置异步库让 MCP 可以非阻塞地处理会话ClientSession 是 SDK 提供的会话管理对象负责和 Server 之间的协议交互AsyncExitStack 是资源管理器保证程序退出时客户端连接能被正确关闭。init里 session 先置为 None因为当前阶段根本没有连接任何 Server。connect_to_mock_server 只是打印一句话目的是让你确认客户端初始化逻辑没报错。chat_loop 是核心交互循环while True 让用户可以连续输入input 拿到文本后 strip 去掉两端空白碰到 quit 就 break任何其他文本都会走 mock 分支返回一条模拟响应。cleanup 在 finally 里调用确保异常退出也能释放资源。3.4 运行与预期输出先验证骨架再谈大模型运行命令很简单python client.py预期输出长这样MCP 客户端已启动输入 quit 退出 Query: hello [Mock Response] 你说的是hello Query: quit到这一步客户端还没有关联任何大模型只是回显输入这是正常的。这个步骤的价值在于验证三件事MCP SDK 安装正确、虚拟环境可用、异步交互循环能正常起停。接下来接入大模型时只需要在这个骨架里替换响应生成部分不用重新搭基础设施。如果你在 Jupyter 里跑注意 asyncio.run 不能嵌套调用需要换成 await main() 的方式这是 Notebook 环境常见的坑先记一下。4. 接入真实大模型在线 API 与本地 ollama/vLLM 的改造路径4.1 新增依赖与 .env 配置密钥和端点分开管基础客户端跑通后下一步接大模型。以在线 API 为例需要安装 openai 兼容的 SDK 和 dotenv 环境变量工具uv add openai python-dotenv然后创建 .env 文件OPENAI_API_KEYsk-你的密钥 OPENAI_BASE_URLhttps://api.example.com/v1 MODEL_NAME你的模型标识逻辑说明OPENAI_API_KEY 存密钥OPENAI_BASE_URL 是服务商的接口地址国内常用在线模型一般也提供兼容格式的端点只需要把 BASE_URL 换成对应地址。MODEL_NAME 填模型标识注意以服务商实际支持为准。dotenv 库负责把 .env 文件里的键值对加载进 os.environ这样代码里不用硬编码密钥。注意.env 文件不要提交到代码仓库常见做法是在 .gitignore 里加上 .env 这一行。4.2 改造 client.py从 Mock 回复到真实工具调用改造分三步。第一步读取环境变量并初始化 openai clientimport os import json import asyncio from pathlib import Path from dotenv import load_dotenv from openai import OpenAI load_dotenv(Path(__file__).parent / .env) client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), )第二步把 MCP 返回的工具列表转换为模型需要的 function 数组。MCP 的 tool 对象自带 name、description、inputSchema 三个字段inputSchema 本身就是 JSON Schema 结构和在线模型的 tools 参数几乎一一对应def to_openai_tools(mcp_tools): functions [] for t in mcp_tools: functions.append({ type: function, function: { name: t.name, description: t.description or , parameters: t.inputSchema, }, }) return functions第三步替换 chat_loop 里的 Mock 逻辑改成完整的“提问 → 模型给工具指令 → 客户端执行 → 结果回传”链路async def chat_loop(self): print(\nMCP 客户端已启动输入 quit 退出) while True: query await asyncio.to_thread(input, \nQuery: ).strip() if query.lower() quit: break messages [{role: user, content: query}] response client.chat.completions.create( modelos.getenv(MODEL_NAME), messagesmessages, toolstools, tool_choiceauto, ) msg response.choices[0].message if msg.tool_calls: for tc in msg.tool_calls: result await self.session.call_tool( nametc.function.name, argumentsjson.loads(tc.function.arguments), ) messages.append({ role: tool, tool_call_id: tc.id, content: str(result), }) final client.chat.completions.create( modelos.getenv(MODEL_NAME), messagesmessages, ) print(f[Agent] {final.choices[0].message.content}) else: print(f[Agent] {msg.content})参数说明tool_choiceauto 表示让模型自己决定要不要调工具msg.tool_calls 是数组因为模型可能一次请求多个工具arguments 是 JSON 字符串必须用 json.loads 解析成对象再传给 call_tool工具执行结果以 roletool 的消息回传并带上 tool_call_id 和模型返回的 id 对应模型才能正确理解结果属于哪次调用。4.3 在线模型接入最小化改动的关键点接入在线模型时BASE_URL 决定了连的是哪家服务代码本身不需要变化。换模型服务商时只需要改 .env 里的三个变量。如果调用失败重点关注两类错误401 表示密钥问题404 或 model_not_found 表示模型标识不对。常见做法是先 curl 一下接口确认连通性再跑代码curl $OPENAI_BASE_URL/models -H Authorization: Bearer $OPENAI_API_KEY返回的 JSON 里会列出该服务商当前可用的模型标识直接比对 .env 里的 MODEL_NAME 就知道配没配错。这个过程能省掉一大半的鉴权故障排查时间。4.4 本地模型接入ollama 与 vLLM 的地址与模型名约定本地模型同样走 OpenAI 兼容端点所以改造后的 client.py 不用动只改 .env 即可。ollama 启动后默认监听 11434 端口兼容端点路径是 /v1vLLM 部署时默认端口 8000模型名由 --served-model-name 参数指定。# ollama 配置 OPENAI_API_KEYollama OPENAI_BASE_URLhttp://localhost:11434/v1 MODEL_NAMEqwen2.5:7b # vLLM 配置 OPENAI_API_KEYvllm OPENAI_BASE_URLhttp://localhost:8000/v1 MODEL_NAME你的模型别名两者的差异主要体现在使用场景上项目ollamavLLM默认端点http://localhost:11434/v1http://localhost:8000/v1模型名来源ollama pull 时的名称--served-model-name 参数适用场景个人开发调试多并发生产或实验室显存开销按需加载预分配且可批量推理本地模型接入有两个高频翻车点ollama 如果没 pull 过对应模型调用会返回 model not foundvLLM 部署时不指定 served-model-name默认用模型路径名客户端传的模型名对不上就会报错。这两个问题后面避坑章会展开讲怎么快速定位。5. MCP 开发避坑指南五个翻车点与对应排查方法5.1 现象一ModuleNotFoundError: mcp现象激活虚拟环境后运行 python client.py提示 No module named mcp。原因最常见是系统里存在多个 Python 解释器激活的虚拟环境和执行 python 命令用的不是同一个或者 uv add 和 pip install 混用包装到了另一个环境里。解决先确认当前 python 指向再看包里有没有最后用 uv 强制装一遍which python # 确认指向 .venv/bin/python pip list | grep mcp uv pip install mcp更稳妥的方式是直接用 uv run python client.pyuv 会自动选择当前项目的虚拟环境不依赖source activate是否生效。这个坑几乎每个 MCP 新手都会踩一次建议把 uv run 当成默认启动命令。5.2 现象二工具列表能拿到调用时报 malformed现象客户端已经通过 list_tools 拿到了工具清单但模型返回的 tool_calls 里 arguments 解析失败或者报 unknown tool。原因MCP SDK 不同版本对 inputSchema 的序列化格式有差异或者模型不支持 Schema 里的某些关键词比如 additionalProperties: false 会被部分在线模型直接拒绝。解决先把实际拿到的 tools 结构打印出来核对格式再在转换函数里做兜底def to_openai_tools(mcp_tools): functions [] for t in mcp_tools: schema t.inputSchema or {type: object, properties: {}} schema.pop(additionalProperties, None) # 去掉部分模型不兼容的字段 functions.append({ type: function, function: { name: t.name, description: t.description or , parameters: schema, }, }) return functions另外把 mcp 版本锁住也能减少这类问题uv add mcp1.0,2.0 可以避免大版本跳跃带来的行为变化。5.3 现象三输入 Query 后客户端像卡死了一样现象chat_loop 里输入文字后没有反应甚至 CtrlC 都失效整个终端像被冻住。原因input() 是同步阻塞函数直接放在 async def chat_loop 里会阻塞事件循环。MCP 的异步调用、openai 的回包处理都依赖事件循环调度输入一直占着线程后面的异步任务永远得不到执行机会。解决把输入放到线程里执行改成 asyncio.to_thread 包装query await asyncio.to_thread(input, \nQuery: ).strip()如果你用的是 Jupyter注意 asyncio.run 不能嵌套使用直接 await main() 或者用 nest_asyncio 处理。这个异步坑在模板代码里看不出来一跑真实模型就现形。5.4 现象四连本地模型 Connection refused现象ollama 或 vLLM 服务已经启动但客户端报连接拒绝或者服务通了却一直说模型不存在。原因本机地址写错常见是少了 /v1 后缀vLLM 端口不是默认的 8000ollama 没有 pull 过对应模型就发请求。解决先用 curl 直接打端点确认服务到底通不通curl http://localhost:11434/v1/models curl http://localhost:8000/v1/modelsollama 返回的 JSON 里有 models 列表vLLM 返回的列表里能看到已加载的模型名。如果 curl 正常但代码里报错检查 .env 的 BASE_URL 和 MODEL_NAME 是否和 curl 返回的一致。vLLM 部署时加 --served-model-name 指定对外名称是避免名称对不上最直接的办法。5.5 现象五API Key 是对的却报鉴权失败现象在线服务返回 401 或 Invalid API key但密钥复制到官网控制台验证是有效的。原因.env 文件没被加载或者文件放错了目录。load_dotenv() 默认只找当前工作目录的 .env从别的目录启动项目就会漏加载os.getenv 取到 None请求带着空密钥自然被拒。解决用显式的文件路径加载并打印校验位from pathlib import Path from dotenv import load_dotenv load_dotenv(Path(__file__).parent / .env) key os.getenv(OPENAI_API_KEY, ) print(fkey prefix: {key[:8]})这个坑我踩过一次排查了半天最后发现是启动目录不对。从那以后凡是 .env 相关代码我都强制用 Path(file).parent 来定位而不是依赖当前工作目录。6. 进阶验证天气查询 Server 的最小实现与 Inspector 联调6.1 一个能跑的天气 Serverlist_tools 与 call_tools客户端链路通了之后值得自己写一个 Server 加深理解。最小实现只需要两个入口import asyncio from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent server Server(weather) server.list_tools() async def list_tools(): return [ Tool( nameget_weather, description查询指定城市的当前天气, inputSchema{ type: object, properties: { city: {type: string, description: 城市名例如 某城市} }, required: [city], }, ) ] server.call_tool() async def call_tool(name: str, arguments: dict): if name get_weather: city arguments[city] # 常见做法这里接入真实天气 API没有 Key 可以先返回 mock 数据 return [TextContent(typetext, textf{city} 当前天气晴25 度)] raise ValueError(f未知工具: {name}) async def main(): async with stdio_server() as (read_stream, write_stream): await server.run( read_stream, write_stream, server.create_initialization_options(), ) if __name__ __main__: asyncio.run(main())list_tools 返回工具清单call_tool 是实际执行入口。stdio_server 走标准输入输出适合本地联调后续部署到远程时改成 Streamable HTTP 即可协议层动作不变。6.2 用 Inspector 完成协议级验证写完 Server 不要急着写客户端先用官方 Inspector 做协议级验证npx modelcontextprotocol/inspector uv run server.pyInspector 启动后浏览器里可以看到 Server 注册的工具列表手动填入参数调用观察返回结果。工具没注册、Schema 不合法、返回类型不对都会直接反馈在界面上比先写客户端再联调快得多。从那以后我每次写完 Server都强制走一遍 Inspector 验证再进客户端联调省掉了大量来回查日志的时间。希望帮到你。进阶方向也很清晰本地验证通过后把传输层从 stdio 换成 Streamable HTTP 部署到远程机器任意 MCP 客户端都能跨机器调用再往后可以试试给 Server 加资源与提示词能力把记忆、上下文、工具三件事整合到一个 Server 里。完整课件和示例代码按资源包里的目录顺序推一遍基本不会卡壳。本文还有配套的精品资源点击获取
