从零到一MCP工具集实战：编写能被Claude Code调用的工具

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 架构，可以理解为三个核心参与者，通过两层协议进行协作。

三个核心参与者（来源：MCP 官方架构文档，2025-06-18）：

两种传输协议：

• 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 来管理依赖，速度比 pip 快不少。

# 安装 uv（macOS/Linux）
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 创建项目
uv init my-mcp-server
cd my-mcp-server

# 激活虚拟环境
uv venv && source .venv/bin/activate   # Windows: .venvScriptsactivate

# 安装 MCP SDK（需 1.2.0+）
uv add "mcp[cli]" httpx

# 创建服务器文件
touch server.py

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

环境搭好了，下面来点真格的。用 FastMCP，定义一个工具只需要一个装饰器，非常简洁。下面是一个查询美国天气预警的完整示例（改自官方 Quickstart）：

# server.py
from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-weather-server")   # Server 名称

NWS_API_BASE = "https://api.weather.gov"

@mcp.tool()
async def get_weather_alerts(state: str) -> str:
    """获取美国某州的天气预警信息。

    Args:
        state: 两字母州代码，如 CA、NY
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    async with httpx.AsyncClient() as client:
        try:
            resp = await client.get(
                url,
                headers={"User-Agent": "mcp-demo/1.0"},
                timeout=30.0
            )
            resp.raise_for_status()
            data = resp.json()
        except Exception as e:
            return f"请求失败：{e}"

    if not data.get("features"):
        return f"{state} 当前无天气预警"

    alerts = []
    for feat in data["features"][:3]:  # 只取前 3 条
        p = feat["properties"]
        alerts.append(f"- {p.get('event','未知')}：{p.get('areaDesc','')}")
    return "n".join(alerts)


@mcp.tool()
def calculate(expression: str) -> str:
    """计算数学表达式。

    Args:
        expression: 数学表达式，如 '2 + 3 * 4'
    """
    try:
        result = eval(expression, {"__builtins__": {}})
        return str(result)
    except Exception as e:
        return f"计算错误：{e}"


if __name__ == "__main__":
    mcp.run()   # 默认使用 Stdio 传输

几个关键点，值得留意：

• @mcp.tool() 这个装饰器，会自动从函数签名和 docstring 生成工具定义（包括名称、描述、参数 Schema）。你完全不需要手写冗长的 JSON 文件，这个设计非常贴心。
• 函数的 docstring 就是工具的描述。在给 AI 使用时，这个描述至关重要——写清楚了，AI 才知道什么时候该调用它。所以，务必用心写好 docstring。
• 在 STDIO 模式下，千万不要用 print() 来输出日志，因为它会污染协议通信。正确的做法是使用 print(..., file=sys.stderr) 或者 logging 模块。

第三步：接入 Claude Code / Claude Desktop

工具写好了，怎么让 Claude 用上它呢？

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 mcp add my-weather-server 
  uv --directory /你的项目绝对路径/my-mcp-server run server.py

保存配置并重启 Claude Desktop 后，或者在 Claude Code 的新会话中，输入 /mcp 确认 Server 已经成功加载。之后，你直接跟 AI 说一句"查一下 CA 的天气预警"，它就会自动调用你刚写的 get_weather_alerts 工具。整个过程非常流畅。

不想自己写？7 个官方 Server 开箱即用

如果你暂时不想从零开始，官方参考 Server 仓库提供了几个非常实用的实现，可以直接拿来用（来源：GitHub modelcontextprotocol/servers，2026-07-01）：

以 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 接入，适合需要对外提供服务或团队协作的场景。

常见问题

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 怎么选？

如果是本地单机使用，比如配合 Claude Desktop 或 Claude Code，选 Stdio 模式最合适：零延迟、可以访问本地文件系统和数据库，接入最简单。如果需要部署到服务器上供团队共用，或者需要对外提供服务，那就选 Streamable HTTP：它支持 OAuth 鉴权，一个 Server 可以同时服务多个 Client。通常的建议是，开发和测试阶段用 Stdio，正式对外提供服务时再迁移到 HTTP。

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

非常重要。AI 依赖工具的 description 字段来决定"要不要调这个工具"。描述写得太模糊，AI 要么不调用，要么就会调错。最佳实践是：首句用一句话说清楚工具是干什么的；Args 部分详细说明每个参数的含义和格式；必要时还可以加一个使用示例。可以把 docstring 理解成一份写给 AI 看的函数文档，写得越清晰，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 以最新版本为准。

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：从零到一MCP工具集实战：编写能被Claude Code调用的工具要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题