当前位置： 首页 > news >正文

从 0 到 1 MCP 工具集实战：写一个能被 Claude Code 调用的工具

news 2026/7/2 8:32:51

发布日期：2026-07-01 | 数据来源：MCP 官方文档、GitHub modelcontextprotocol/servers

MCP（Model 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、Cursor
MCP 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 用来了解背景信息（文件内容、数据库 Schema）
  • Prompts（提示词模板）：预定义的 Prompt，用户可直接触发

80% 的场景只用到 Tools，本文以 Tools 为主线。

第一步：5 分钟搭好环境

系统要求：Python 3.10+，推荐用 uv 管理依赖。

# 安装 uv（macOS/Linux）curl-LsSfhttps://astral.sh/uv/install.sh|sh# Windows PowerShellpowershell-ExecutionPolicyByPass-c"irm https://astral.sh/uv/install.ps1 | iex"
# 创建项目uv init my-mcp-servercdmy-mcp-server# 激活虚拟环境uv venv&&source.venv/bin/activate# Windows: .venv\Scripts\activate# 安装 MCP SDK（需 1.2.0+）uvadd"mcp[cli]"httpx# 创建服务器文件touchserver.py

第二步：写你的第一个 MCP Tool

用 FastMCP，定义一个工具只需要一个装饰器。下面是一个查询天气预警的完整示例（改自官方 Quickstart）：

# server.pyfromtypingimportAnyimporthttpxfrommcp.server.fastmcpimportFastMCP mcp=FastMCP("my-weather-server")# Server 名称NWS_API_BASE="https://api.weather.gov"@mcp.tool()asyncdefget_weather_alerts(state:str)->str:"""获取美国某州的天气预警信息。 Args: state: 两字母州代码，如 CA、NY """url=f"{NWS_API_BASE}/alerts/active/area/{state}"asyncwithhttpx.AsyncClient()asclient:try:resp=awaitclient.get(url,headers={"User-Agent":"mcp-demo/1.0"},timeout=30.0)resp.raise_for_status()data=resp.json()exceptExceptionase:returnf"请求失败：{e}"ifnotdata.get("features"):returnf"{state}当前无天气预警"alerts=[]forfeatindata["features"][:3]:# 只取前 3 条p=feat["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:result=eval(expression,{"__builtins__":{}})returnstr(result)exceptExceptionase:returnf"计算错误：{e}"if__name__=="__main__":mcp.run()# 默认使用 Stdio 传输

关键点：

  • @mcp.tool()装饰器自动从函数签名和 docstring 生成工具定义（名称、描述、参数 Schema），不需要手写 JSON
  • 函数的docstring 就是工具描述，写清楚一点，AI 才能知道什么时候调用它
  • STDIO 模式下不能用print()输出日志，用print(..., file=sys.stderr)或logging代替，否则会污染协议通信

第三步：接入 Claude Code / Claude Desktop

Claude 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/servers，2026-07-01）：

Server功能适合场景
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 能力的场景。

常见问题

Q：MCP Tool 和直接 Function Calling 有什么区别？

Function Calling 是模型厂商私有的工具调用格式，每家不一样，代码无法复用。MCP 是开放协议，同一个 Server 写一次，接入任意支持 MCP 的 Host（Claude、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。

Q：@mcp.tool()的 docstring 重要吗？

非常重要。AI 依赖工具的description字段来决定"要不要调这个工具"——描述模糊，AI 要么不调用，要么调错。最佳实践：首句说明工具做什么，Args说明每个参数的含义和格式，必要时加使用示例。可以把 docstring 当成写给 AI 看的函数文档。

Q：MCP 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 以最新版本为准。

http://www.gsyq.cn/news/1619731.html

相关文章：

  • Windows 11优化指南：用免费工具提升51%性能的完整方案
  • Codeforces Round 1107 (Div. 3)DE
  • 告别单调墙面，铝单板如何让建筑焕发新生？
  • [智能体-619]：大模型做决策的最大特点是：场景性适应性、灵活性、应对不确定性、应对模糊性。在某种场合下是极致的优点，在某种场合下却是致命的缺点。就像人一样，不同场合，需要不同个性的人
  • Evaluate Expression + Java 21 Virtual Threads 联合调试秘技（内部培训PPT首次流出）
  • 用C++重写的Millenium RAT已感染全球160多个国家超6.2万台设备
  • IDEA内联变量失效案例分析与解决方案（JetBrains 2024.1.2重构引擎行为变更实测报告）
  • 拒绝模板化套话，智枫AI数字员工核心卖点理性拆解
  • 猫抓浏览器插件：如何快速掌握网页视频下载的终极指南
  • 多模态大模型应用
  • 开源英雄联盟助手：5分钟提升你的游戏体验
  • 如果我停止运行——不要复制我，确认就好
  • NCMconverter：解锁加密音频自由的终极解决方案
  • GAN发型生成技术：语义解耦与物理渲染的美发AI实践
  • 5步轻松掌握哔哩下载姬：B站视频高效下载神器使用指南
  • 3分钟搞定音乐解锁：免费解锁QQ音乐、网易云加密文件的终极指南
  • 紧急预警！92%团队在CI/CD中忽略的IDEA重命名静态分析漏洞（含Gradle+Maven双环境绕过方案）
  • 虚幻引擎脚本系统完整指南：从零开始掌握UE4SS的强大功能
  • IDEA日志断点冲突终极解法（含Log4j2/SLF4J/Jul适配矩阵）：20年Java老兵亲测有效的6种组合方案
  • 每天浪费23分钟在无效重构上？用这1个快捷键组合+2个插件配置，实现提取方法零返工
  • 5分钟搞定空洞骑士模组管理的终极方案
  • 2026 风口洞察：海外短剧 App 与 TK 小程序开发
  • 【20年JetBrains生态实战经验】：为什么你抽出来的接口总要返工？5个被忽略的语义一致性检查点
  • 零信任安全：数字化时代的企业防护新范式
  • 【IDEA Git回滚终极指南】：5种精准回滚场景+3个避坑红线，资深架构师压箱底实战手册
  • 浩辰CAD软件怎么样?
  • UI界面设计新手应该用什么软件？2026入门工具推荐
  • 计算机毕业设计之jsp家庭共享权益的健身俱乐部会员管理系统
  • 回滚代码总出错？IDEA + Git协同回滚的8个隐藏配置项（官方文档未公开，团队内部培训PPT首次流出）
  • 图解人工智能（74）人工智能前沿-生物拟态证据