从客户端到天气服务器：MCP 快速入门与工具调用实战

简介《从零到一MCP快速入门实战》面向希望系统理解并上手Model Context Protocol的开发者与Agent学习者从技术体系、客户端开发到服务器搭建逐步展开适合具备Python基础、想降低外部工具调用门槛的初中级读者。资源包共1个PDF文件约47.66MB内容以图文教程形式组织围绕MCP入门、Function calling回顾、uv环境管理、极简客户端搭建、在线与本地模型接入、天气查询服务器与客户端实现、MCP Inspector及进阶功能展开。已有1127人学习说明其内容具备一定参考热度。读者可沿目录梳理MCP开发流程掌握客户端与服务器通信机制理解OpenAI、DeepSeek、ollama、vLLM等模型的接入思路并借助示例代码与运行说明完成从环境准备到联调测试的实践形成较完整的入门路径。1. 为什么我先写客户端再写服务器MCP 快速入门的一次顺序调整很多人第一次接触 Model Context Protocol下面统一叫 MCP时会照着各种教程先搭服务器、再写客户端结果卡在配置和联调上半天找不出问题。我在一次 Agent 工具链的项目里反着试了一遍先用几十行代码把 MCP 客户端跑通让它能启动、能接收输入、能优雅退出然后再回头去接天气查询服务器。这个顺序调整带来的直接好处是——出问题时你能立刻判断是客户端环境的问题还是服务器协议的问题而不是面对一堆堆栈信息靠猜。这套「从零到一 MCP 快速入门实战」资料讲的就是这条路径先讲清 MCP 的技术体系与 Function calling 的关系再拆客户端从 uv 环境、极简骨架到接入在线模型和本地模型最后落到天气查询服务器的完整实现与 MCP Inspector 调试。适合刚接触 Agent 开发、想把外部工具接进大模型但被 Function calling 那一堆 JSON Schema 劝退的开发者也适合已经会用大模型 API、想搞明白 MCP 到底省了哪些事的熟手。2. MCP 技术体系与工程前置先把协议和 uv 环境搞明白MCP 本质上是一份协议不是某个库也不是某个框架。它把「大模型运行环境」叫 MCP Client把「外部函数运行环境」叫 MCP Server然后统一两者之间的通信规范。理解这一点后面所有代码才有落点客户端负责把你的自然语言请求翻译成工具调用服务器负责真正执行工具并把结果返回。这份资料在第一章就把这层关系讲透了还顺带回顾了 Function calling 和大模型 Agent 的技术体系避免你直接用 SDK 却不知道 SDK 在替你做什么。2.1 协议层要解决的问题为什么不是直接写 Function calling传统 Function calling 的流程是你写一个外部函数再手写一份 JSON Schema 描述它的参数再设计一段提示词模板提高调用准确率最后把这三样东西一起喂给模型。一个查天气的函数光描述和容错就得几十上百行。麻烦的地方不在于写函数而在于每接一个新工具就要重复一遍这套动作而且每个模型的 Schema 格式还不完全一致。MCP 的做法是把这套约定固化成协议工具的描述、调用、返回都走同一套消息格式客户端和服务器各自实现自己那一半。于是「查天气」这种通用能力一个人写好服务器其他人直接复用。我在实际项目里最直观的感受是以前接三个工具要写三份提示词模板现在客户端侧基本不用动换服务器就行。对比项传统 Function callingMCP工具描述每个函数手写 JSON Schema服务器自描述客户端自动发现提示词模板每个工具单独设计协议统一客户端复用复用方式复制函数代码直接连接现成服务器调试手段打日志看请求Inspector 可视化查看消息这张表不是让你背而是帮你判断什么时候值得上 MCP工具数量少、模型固定Function calling 够用工具多、要换模型、要复用社区生态MCP 的收益才明显。2.2 uv 的安装与虚拟环境初始化MCP 的官方示例和社区项目基本都推荐用 uv 管环境原因是它用 Rust 写的装包快而且能直接读 pyproject.toml避免 pip 那种依赖解析慢、版本冲突排查难的问题。安装有两条路装了 pip 的直接装没有的用脚本装。# 方式一已有 pip 环境 pip install uv # 方式二无 pip 的系统用官方脚本安装 curl -LsSf https://astral.sh/uv/install.sh | sh装完之后验证一下版本能打印出来就说明 PATH 没问题uv --version这里有个容易翻车的点用脚本安装后当前终端可能还没刷新 PATH直接敲 uv 会提示 command not found。重新开一个终端或者手动 source 一下 shell 配置文件就能解决不用重装。接下来创建项目和环境。uv 和 pip 最大的行为差异是它会自动识别当前项目主目录并把虚拟环境建在.venv下不需要你手动指定路径# 初始化项目生成 pyproject.toml uv init mcp-client cd mcp-client # 创建虚拟环境默认落在 .venv uv venv # 激活环境Linux/macOS 用这条 source .venv/bin/activate # Windows 用这条 # .venv\Scripts\activate激活之后安装 MCP SDK。注意这里用的是uv add而不是uv pip install前者会把依赖写进 pyproject.toml后者只装不进清单团队协作时别人拉代码就装不齐uv add mcp提示如果你在 Jupyter 里跑激活虚拟环境这一步可以跳过但要确保 notebook 的 kernel 选的是这个.venv对应的解释器否则会出现「命令行装好了、notebook 里 import 报错」的情况。2.3 环境层面的常见误用我见过最多的误用是混用 pip 和 uv。比如先用pip install mcp装在全局又用 uv 建了个空环境然后激活环境跑代码报 ModuleNotFoundError人就开始怀疑是不是 SDK 有问题。实际上全局装的包和虚拟环境是两套隔离的 site-packages激活环境后就只看环境内的包。另一个误用是不看 pyproject.toml 就乱加依赖。uv 的项目模式下依赖声明在 pyproject.toml 里uv add会自动维护手动改文件再uv sync也行但别两边同时改容易把锁文件搞乱。真乱了就删掉uv.lock重新uv sync这是成本最低的后悔药。3. MCP 客户端搭建从极简骨架到接入在线与本地模型客户端这一层是整个入门路径里性价比最高的部分。先用一个不带任何模型的骨架把异步结构和退出逻辑跑通再往里塞模型出问题时你能明确知道是网络、密钥、还是协议层的问题。资料里的顺序也是这样极简客户端 → 接在线模型 → 接本地模型每一步只加一个变量。3.1 极简客户端的完整代码与结构拆解先在项目根目录建client.py写入下面这段。它不连真实服务器只提供一个命令行循环作用是验证异步框架、资源管理和输入输出都正常。import asyncio from mcp import ClientSession from contextlib import AsyncExitStack class MCPClient: def __init__(self): 初始化 MCP 客户端 self.session None # 用 AsyncExitStack 统一管理异步资源退出时按栈顺序释放 self.exit_stack AsyncExitStack() async def connect_to_mock_server(self): 模拟服务器连接先不接真实 server print(MCP 客户端已初始化但未连接到服务器) async def chat_loop(self): 交互式循环quit 退出 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())逐段说清楚逻辑。asyncio是 Python 内置的异步库MCP 的会话方法都是 async 的所以整个调用链必须跑在事件循环里。AsyncExitStack是上下文管理器栈你可以把它理解成一个「资源登记处」后面真正连服务器时stdio 子进程、HTTP 会话都往这里注册退出时统一关不会漏。session先置为 None 是有意为之骨架阶段不连接任何服务器等联调时再替换connect_to_mock_server的实现。chat_loop里的input()是同步阻塞的放在 async 函数里在单用户命令行场景没问题但如果你要改成并发处理多个请求就得换成异步输入这是后续进阶才需要考虑的事。运行方式和普通脚本一样python client.py看到启动提示、输入任意内容能回显、输入 quit 能正常退出就说明骨架没问题。这里的关键不是功能而是验证了「异步入口 资源栈 循环退出」这三件套后面接模型时只是往循环里填真正的调用逻辑。3.2 接入在线模型环境变量与 client.py 改造接在线模型OpenAI 兼容接口或 DeepSeek 这类时资料里给的路线是先加依赖、再建.env、最后改client.py。依赖侧通常是模型 SDK 加 dotenvuv add openai python-dotenv.env文件放密钥和模型名不要提交到仓库。工程上我一般会同时提交一个.env.example把字段名写清楚别人拉下来复制一份填值就行# .env OPENAI_API_KEYsk-xxxx OPENAI_BASE_URLhttps://api.example.com/v1 MODEL_NAMEyour-model-name改造client.py的核心思路是把 mock 回复替换成模型调用并且把 MCP 工具列表塞进请求里。下面是骨架级的改法重点是消息构造和工具注入的位置import os import asyncio from dotenv import load_dotenv from openai import AsyncOpenAI from mcp import ClientSession from contextlib import AsyncExitStack load_dotenv() # 读取 .env class MCPClient: def __init__(self): self.session None self.exit_stack AsyncExitStack() # 用 base_url 兼容 OpenAI 与各类兼容接口 self.llm AsyncOpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) self.model os.getenv(MODEL_NAME) async def chat_loop(self): messages [] while True: query input(\nQuery: ).strip() if query.lower() quit: break messages.append({role: user, content: query}) # tools 参数来自 MCP 服务器暴露的工具清单 resp await self.llm.chat.completions.create( modelself.model, messagesmessages, toolsself.tools if hasattr(self, tools) else None, ) msg resp.choices[0].message messages.append(msg.model_dump()) print(msg.content or [模型请求调用工具])参数上要留意三点。base_url决定了请求打到哪个服务DeepSeek 和各类兼容网关都是这个套路路径末尾的/v1别漏。tools字段的格式需要从 MCP 工具描述转换过来字段名一般是 name、description、input_schema转换函数写一次就能复用。messages要持续累积多轮对话的上下文靠它维持别每轮重建。注意密钥只放.env代码里一律走os.getenv。我见过把 key 硬编码进 client.py 然后推到公开仓库的只能立刻去后台轮换密钥这种事故没有后悔药。3.3 接入本地模型ollama 与 vLLM 的差异本地模型的接入改动集中在客户端初始化和地址上。ollama 默认在本地起一个 OpenAI 兼容服务端口 11434把 base_url 指过去、模型名换成你 pull 下来的模型即可self.llm AsyncOpenAI( api_keyollama, # 本地服务不校验占位即可 base_urlhttp://localhost:11434/v1, ) self.model qwen2.5 # 换成你本地已有的模型vLLM 的接法几乎一样差别在部署侧vLLM 需要先把模型以 OpenAI 兼容模式起服务默认端口 8000启动命令里要指定模型路径和端口。客户端侧只需要改 base_urlself.llm AsyncOpenAI( api_keyvllm, base_urlhttp://localhost:8000/v1, )这里值得展开的是本地模型和 MCP 配合时的现实约束。MCP 的工具调用依赖模型能稳定输出结构化的工具请求小参数模型在这块经常不稳定表现为该调工具时给你一段自然语言解释。我一般的做法是先把工具数量控制在一两个、描述写得足够直白确认模型能稳定触发再往上加工具。这不是玄学是模型对 Schema 的指令跟随能力问题换更大的模型或者精简工具描述都能缓解。接入方式base_url密钥典型问题在线兼容接口服务商提供必填网络、额度、模型名拼错ollamalocalhost:11434/v1占位即可模型未 pull、端口被占vLLMlocalhost:8000/v1占位即可服务未起、显存不足4. 天气查询服务器实战Server 创建、客户端联调与 Inspector 调试服务器这一章是整套流程的收口。前面客户端能跑、能接模型但模型手里没有任何工具只能聊天。天气查询服务器的作用是把「查天气」这个能力按 MCP 规范暴露出去让客户端发现并调用。资料里的路线是先讲服务器概念和通讯机制再写代码最后用 Inspector 验证这个顺序对新手很友好因为 Inspector 能在不写客户端的情况下先确认服务器本身是通的。4.1 服务器通讯机制与依赖安装MCP 服务器和客户端之间常见的通讯方式有两种stdio 和 SSE/HTTP。stdio 是把服务器作为子进程启动通过标准输入输出传消息适合本地工具HTTP 方式适合部署到远端给多人用。入门阶段基本都用 stdio因为不需要起端口、不需要处理鉴权客户端拉起子进程就能通信。服务器侧依赖装法和客户端一致用 uv 建独立环境更干净避免两个项目的依赖互相污染uv init mcp-weather-server cd mcp-weather-server uv venv source .venv/bin/activate uv add mcp httpxhttpx是用来真正请求天气接口的如果你用 mock 数据可以先不加。工程习惯上我会把服务器和客户端分成两个目录、两个虚拟环境联调时客户端配置里写服务器的启动命令这样两边的依赖版本互不干扰。4.2 天气服务器的代码结构与工具注册服务器的核心是创建一个 Server 实例然后用装饰器把函数注册成工具。工具函数的参数类型标注会被 SDK 自动转成 JSON Schema这正是 MCP 省掉手写 Schema 的地方。下面是一个结构完整的示例import asyncio import httpx from mcp.server import Server from mcp.server.stdio import stdio_server app Server(weather-server) app.tool() async def get_weather(city: str) - str: 查询指定城市的当前天气 Args: city: 城市名称例如 北京 # 实际项目替换为真实天气接口示例用占位地址 async with httpx.AsyncClient(timeout10) as client: resp await client.get( https://api.example.com/weather, params{city: city}, ) resp.raise_for_status() data resp.json() return f{city} 当前温度 {data[temp]}℃{data[desc]} async def main(): # stdio 模式由客户端拉起本进程并接管标准输入输出 async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ __main__: asyncio.run(main())关键点在几处。app.tool()装饰器负责注册函数名就是工具名docstring 会成为工具描述模型靠这段描述判断什么时候该调。参数city: str的类型标注会被转成 Schema 的 string 类型如果你写city: int模型就会按整数传参所以标注必须和真实语义一致。timeout10是必须的外部接口不设超时会让整个工具调用卡死客户端侧表现为长时间无响应很难排查。stdio_server()返回读写流run方法把服务器挂上去。这段代码不需要你手动处理消息帧SDK 全包了。真要改造成支持多个工具就再写几个带app.tool()的函数客户端重新连接时自动发现。4.3 客户端连接真实服务器与工具调用闭环客户端侧要从 mock 切换到真实连接核心是启动服务器子进程并建立会话。资料里的写法是用 stdio 客户端参数拉起命令from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def connect_to_server(self, server_script_path: str): 拉起服务器子进程并建立 MCP 会话 params StdioServerParameters( commandpython, args[server_script_path], envNone, # 需要环境变量时在这里传 ) # 注册到 exit_stack退出时自动关闭子进程 read, write await self.exit_stack.enter_async_context( stdio_client(params) ) self.session await self.exit_stack.enter_async_context( ClientSession(read, write) ) await self.session.initialize() # 拉取服务器暴露的工具列表 tools await self.session.list_tools() print(f已连接可用工具{[t.name for t in tools.tools]})参数说明command是启动服务器的解释器用绝对路径更稳避免虚拟环境解释器不一致args是服务器脚本路径env在需要透传 API key 时使用不传就继承当前进程环境。initialize()是握手必须调否则后续list_tools会报会话未就绪。把 read/write 和 session 都进 exit_stack是为了保证异常退出时子进程被回收不然会在系统里留一堆孤儿进程。工具清单拿到之后把它转成模型 API 需要的 tools 格式在 chat_loop 里判断模型返回是否包含工具调用有就通过self.session.call_tool(name, arguments)执行再把结果作为工具消息塞回对话。这一步跑通整个「模型 → 工具 → 结果 → 模型」的闭环就成立了。4.4 MCP Inspector把黑匣子打开Inspector 是官方提供的调试工具作用是让你不写任何客户端代码就能连上服务器看到它暴露了哪些工具、参数结构长什么样、调用返回什么。我一般在新写一个服务器后第一件事就是用它验证比直接联调客户端快得多。启动方式通常是 npx 拉起来然后在界面里选择 stdio、填启动命令和脚本路径连上之后左侧会列出 tools点进去能直接填参数调用。它的价值在于把协议消息可视化了你能看到工具描述的原文如果模型不调工具先来这里看描述是不是写得太含糊比在代码里加日志高效。提示Inspector 连不上时先手动在终端跑一遍服务器脚本看有没有 import 错误或启动即崩。Inspector 报连接失败十有八九是服务器自己起不来而不是 Inspector 的问题。5. 联调避坑五个真实踩过的坑与排查路径这一章单独拿出来是因为 MCP 的问题大多不在代码逻辑而在环境、进程和协议细节上。下面五条按「现象 → 原因 → 解决」写都是我在实际搭这套东西时真碰到的。现象一客户端启动后一直卡住没有任何输出。原因通常是服务器子进程启动失败但客户端在等握手两边互相等。解决把服务器脚本单独在终端跑一遍看是否报 ModuleNotFoundError 或语法错误确认客户端配置的解释器路径和服务器所在虚拟环境一致。现象二list_tools 返回空列表。原因多为工具注册没生效比如装饰器写在类方法上但没实例化或者服务器启动的是旧版本脚本。解决确认app.tool()装饰的函数在模块顶层或已被执行到改完代码重启客户端stdio 模式下服务器是随客户端拉起的不重启不会加载新代码。现象三模型不调用工具只回一段文字。原因有两个方向工具描述太模糊或者模型本身指令跟随弱。解决先把 docstring 改成「什么时候用、参数是什么」的直白描述在 Inspector 里确认描述已生效再换一个能力更强的模型验证确认是模型问题还是描述问题。现象四工具调用报参数校验失败。原因是 Schema 和实际传参不一致典型是类型标注写成 str 但模型传了数字或者必填参数没给默认值。解决检查函数签名能设默认值的参数给上默认值类型标注和真实语义对齐改完在 Inspector 里手动调一次确认。现象五程序退出后系统里残留 python 进程。原因是子进程没被回收通常是没走 exit_stack 或者异常路径跳过了 cleanup。解决确认 read/write 和 session 都通过enter_async_context注册main 里用 try/finally 包住保证异常也会执行清理。注意这五条里有四条都能用同一个动作定位——单独跑服务器 Inspector 验证。养成「先证明服务器是通的再怀疑客户端」的习惯能省掉大量时间。6. 二次开发怎么改从天气 Demo 到自己的工具服务器把 Demo 跑通只是起点真正有价值的是照着这套结构换成自己的工具。改造路径我一般按三步走每一步都能独立验证不会一次改太多导致问题定位不了。第一步是换工具实现不动协议层。比如你要接的是本地数据库查询就把get_weather换成query_db参数改成sql: str函数体里换成数据库连接和查询。这里有个血泪经验工具函数一定要做输入校验和超时控制模型生成的参数不可信直接把模型给的字符串拼进 SQL 是灾难。我一般会限制只允许 SELECT、加超时、返回结果截断到合理长度避免一次查询把上下文撑爆。第二步是加工具数量时控制描述质量。工具不是越多越好模型在几十个工具里选择时准确率会下降。我的做法是按业务域拆服务器一个服务器只管一类能力客户端按需连接。下面这张表是我改造时常用的检查项改造点检查内容验证方式工具描述是否写清何时使用、参数含义Inspector 查看描述原文参数类型标注与真实语义是否一致手动传边界值调用异常处理超时、空结果、接口报错断网或传错参数测试返回体大小是否截断是否含敏感信息打印实际返回长度第三步是把服务器从 stdio 改成可部署形态。stdio 适合本地单人用要给团队共用就得走 HTTP 方式这时要考虑鉴权、并发和日志。改造时协议层的代码基本不动换的是传输层和启动方式这也是 MCP 分层设计带来的好处——工具逻辑和通讯方式解耦。验证方法上我习惯每改完一个工具就跑三遍Inspector 手动调一次确认参数和返回正确客户端里用自然语言问一次确认模型能选中再问一次不相关的问题确认模型不会乱调。三遍都过这个工具才算能用。从那以后我每次接新工具都强制先写服务器、用 Inspector 验证通过再去动客户端和模型配置绝不在客户端里一边调协议一边调业务。这个顺序看起来慢实际省下的排查时间远超想象。希望这套路径能帮你少走几个弯路把 MCP 真正用进自己的项目里。本文还有配套的精品资源点击获取