发布日期2026-07-01 | 数据来源MCP 官方文档、GitHub modelcontextprotocol/serversMCPModel Context Protocol模型上下文协议是 Anthropic 于 2024 年推出的开源标准定义了 AI 应用与外部系统之间的标准化连接方式——可以理解为AI 的 USB-C 接口同一个 MCP Server写一次接入 Claude Code、VS Code Copilot、Cursor、ChatGPT 等任意支持 MCP 的客户端无需为每个工具单独适配。本文从零开始用 Python FastMCP 写一个可被 Claude Code 实际调用的工具覆盖架构理解 → 环境搭建 → 工具定义 → 客户端接入的完整链路并附上 7 个官方开箱即用的 Server 推荐。先把架构搞清楚三个角色两层协议三个核心参与者来源MCP 官方架构文档2025-06-18角色是什么举例MCP Host运行 AI 应用的宿主管理所有 Client 连接Claude Code、Claude Desktop、VS Code、CursorMCP ClientHost 为每个 Server 创建的独立连接对象Host 内部自动创建开发者无需关心MCP Server暴露工具、数据、提示词的程序你自己写的 weather.py、官方 Filesystem Server两种传输协议Stdio标准输入输出本地进程通信零网络开销Claude Desktop / Claude Code 接入本地 Server 时使用Streamable HTTP远程服务器通信支持 SSE 流式推送适合部署到云端对外提供的 Server三种 Server 原语你能提供给 AI 的三类能力Tools工具可执行的函数AI 会调用它完成动作查数据库、调 API、操作文件Resources资源只读数据上下文AI 用来了解背景信息文件内容、数据库 SchemaPrompts提示词模板预定义的 Prompt用户可直接触发80% 的场景只用到 Tools本文以 Tools 为主线。第一步5 分钟搭好环境系统要求Python 3.10推荐用 uv 管理依赖。# 安装 uvmacOS/Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|sh# Windows PowerShellpowershell-ExecutionPolicyByPass-cirm https://astral.sh/uv/install.ps1 | iex# 创建项目uv init my-mcp-servercdmy-mcp-server# 激活虚拟环境uv venvsource.venv/bin/activate# Windows: .venv\Scripts\activate# 安装 MCP SDK需 1.2.0uvaddmcp[cli]httpx# 创建服务器文件touchserver.py第二步写你的第一个 MCP Tool用 FastMCP定义一个工具只需要一个装饰器。下面是一个查询天气预警的完整示例改自官方 Quickstart# server.pyfromtypingimportAnyimporthttpxfrommcp.server.fastmcpimportFastMCP mcpFastMCP(my-weather-server)# Server 名称NWS_API_BASEhttps://api.weather.govmcp.tool()asyncdefget_weather_alerts(state:str)-str:获取美国某州的天气预警信息。 Args: state: 两字母州代码如 CA、NY urlf{NWS_API_BASE}/alerts/active/area/{state}asyncwithhttpx.AsyncClient()asclient:try:respawaitclient.get(url,headers{User-Agent:mcp-demo/1.0},timeout30.0)resp.raise_for_status()dataresp.json()exceptExceptionase:returnf请求失败{e}ifnotdata.get(features):returnf{state}当前无天气预警alerts[]forfeatindata[features][:3]:# 只取前 3 条pfeat[properties]alerts.append(f-{p.get(event,未知)}{p.get(areaDesc,)})return\n.join(alerts)mcp.tool()defcalculate(expression:str)-str:计算数学表达式。 Args: expression: 数学表达式如 2 3 * 4 try:resulteval(expression,{__builtins__:{}})returnstr(result)exceptExceptionase:returnf计算错误{e}if__name____main__:mcp.run()# 默认使用 Stdio 传输关键点mcp.tool()装饰器自动从函数签名和 docstring 生成工具定义名称、描述、参数 Schema不需要手写 JSON函数的docstring 就是工具描述写清楚一点AI 才能知道什么时候调用它STDIO 模式下不能用print()输出日志用print(..., filesys.stderr)或logging代替否则会污染协议通信第三步接入 Claude Code / Claude DesktopClaude Desktop~/Library/Application Support/Claude/claude_desktop_config.json{mcpServers:{my-weather-server:{command:uv,args:[--directory,/你的项目绝对路径/my-mcp-server,run,server.py]}}}Claude Code命令行添加claude mcpaddmy-weather-server\uv--directory/你的项目绝对路径/my-mcp-server run server.py保存后重启 Claude Desktop或在 Claude Code 新会话中输入/mcp确认 Server 已加载。然后直接跟 AI 说查一下 CA 的天气预警它会自动调用你刚写的get_weather_alerts工具。不想自己写7 个官方 Server 开箱即用官方 Reference Server 仓库提供了以下可直接使用的实现来源GitHub modelcontextprotocol/servers2026-07-01Server功能适合场景Filesystem安全文件读写可配置访问范围让 AI 读写本地文件Git读取、搜索、操作 Git 仓库代码库分析、commit 查询Memory基于知识图谱的持久化记忆跨会话保存上下文Fetch抓取网页并转为 LLM 可读格式让 AI 读任意网页Sequential Thinking结构化思维链推理工具复杂问题分步推理Time时间查询与时区转换时间相关任务PostgreSQL只读数据库访问 Schema 查询数据库问答以 Filesystem Server 为例claude_desktop_config.json中添加{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,/Users/你的用户名/Documents]}}}进阶用 MCP Inspector 调试工具官方提供了可视化调试工具 MCP Inspector不需要启动 Claude Desktop 就能测试你的 Server# 安装并启动npx modelcontextprotocol/inspector uv--directory.run server.py打开浏览器的调试界面可以手动触发tools/list和tools/call实时看到请求响应的 JSON比直接在 Claude 里测试效率高得多。不想本地部署云端 MCP 服务如果不想在本地维护 MCP Server 进程七牛云提供了云端 MCP 服务——标准化模型能力编排平台无需本地部署即可构建 Agent 应用直接通过 Streamable HTTP 接入适合需要对外提供服务或团队共享 MCP 能力的场景。常见问题QMCP Tool 和直接 Function Calling 有什么区别Function Calling 是模型厂商私有的工具调用格式每家不一样代码无法复用。MCP 是开放协议同一个 Server 写一次接入任意支持 MCP 的 HostClaude、ChatGPT、VS Code 等无需修改。MCP 的底层依然走 JSON-RPC可以理解为标准化的 Function Calling 注册中心来源MCP 官方文档。Q本地 Stdio Server 和远程 Streamable HTTP Server 怎么选本地 Server 用 Stdio零延迟可访问本地文件系统和数据库Claude Desktop / Claude Code 接入最简单。远程 Server 用 Streamable HTTP可以部署到服务器供团队共用支持 OAuth 鉴权一个 Server 同时服务多个 Client。开发和测试阶段用 Stdio需要对外提供服务时迁移到 HTTP。Qmcp.tool()的 docstring 重要吗非常重要。AI 依赖工具的description字段来决定要不要调这个工具——描述模糊AI 要么不调用要么调错。最佳实践首句说明工具做什么Args说明每个参数的含义和格式必要时加使用示例。可以把 docstring 当成写给 AI 看的函数文档。QMCP Server 能同时暴露 Tools 和 Resources 吗可以。同一个 Server 可以同时定义mcp.tool()、mcp.resource()和mcp.prompt()Client 通过tools/list、resources/list、prompts/list分别发现。实际项目中通常用 Resources 提供数据库 Schema 作为背景上下文用 Tools 执行具体查询操作两者配合使用效果最好。权威来源MCP Build Server 教程GitHub: modelcontextprotocol/servers官方 Reference Servers云端 MCP 服务七牛云 MCP 使用手册本文代码基于 MCP Python SDK 1.2.0官方 API 以最新版本为准。