用 FastMCP 快速为 Claude Code 构建自定义工具服务器

用 FastMCP 快速为 Claude Code 构建自定义工具服务器 | 前端进阶之旅

Full translation

完整中文译文

"MCP 服务器听起来很复杂"——如果你是这么想的，FastMCP 或许会改变你的看法。它几乎帮你处理了所有的底层 plumbing。只需给一个普通的 Python 函数加上一个装饰器，你就拥有了一个 Claude Code 可以调用的自定义工具。

在本文中，我们将以一个小型的算命工具作为学习案例，并沿途讲解 FastMCP 实际上在背后为你做了什么。

MCP（Model Context Protocol）是一个通用标准，用于为 Claude 这样的 AI 模型提供"外部工具"。

AI 模型本身很擅长生成文本，但仅靠自身，它无法完成诸如"根据日期算今日运势"或"查询内部数据库"这类具体的事情。

这时 MCP 服务器就派上用场了：你在上面注册可调用的工具，Claude Code 在需要时会调用它们。

从头手写一个 MCP 服务器工作量不小，但有了 FastMCP，你只需几十行代码就能构建一个可用的算命工具，Claude Code 可以直接调用。

为什么 FastMCP 让这件事变得简单

通常，一个 MCP 服务器需要实现大量底层协议细节——使用什么消息格式、如何通告可用工具列表，等等。FastMCP 为你处理了所有这些"管道"工作。

作为开发者，你要做的只是写一个普通的 Python 函数，然后用 @mcp.tool 标记它。FastMCP 会检查函数的参数类型和返回值类型，自动生成 schema（也就是"说明书"），交给 AI。由于传输层或协议细节都不需要你操心，任何写过基本 Web 应用的人都能在几分钟内让第一个工具跑起来。

关于装饰器语法的一个提示：独立的 fastmcp 包（我们这里使用的）接受不带括号的 @mcp.tool。如果你使用的是官方 mcp Python SDK 捆绑的 MCPServer，装饰器需要加括号：@mcp.tool()。混用这两者是一种常见的令人困惑的错误来源，所以如果你从其他 MCP 教程复制代码，要仔细检查它使用的是哪个包。

设置 Python 环境

你需要 Python 3.10 或更高版本。

python --version

如果没有安装，从 python.org 下载。

然后创建并激活虚拟环境：

# macOS / Linux
python -m venv venv
source venv/bin/activate

# Windows
python -m venv venv
venv\Scripts\activate.bat

激活后，你会在提示符开头看到 (venv)。

pip install fastmcp

就这样——无需数据库，无需配置文件。

构建算命工具

创建一个项目文件夹，在其中新建一个 server.py 文件，内容如下：

import random
from datetime import date
from fastmcp import FastMCP

# Create the server ("uranai" is Japanese for "fortune-telling" — the name of this tool group)
mcp = FastMCP("uranai")

@mcp.tool
def fortune(name: str, birthday: str = "") -> str:
    """Tells today's fortune based on a name (and optionally a birthday)."""
    # Seed the RNG with name + birthday + today's date, so the result
    # stays the same for a given person on a given day, but changes daily.
    seed = f"{name}|{birthday}|{date.today().isoformat()}"
    rng = random.Random(seed)

    levels = ["Great luck", "Good luck", "Modest luck", "Luck", "Fading luck", "Bad luck"]
    items = ["reading a book", "taking a walk", "coffee", "sleeping early", "a new app", "cleaning"]
    colors = ["red", "blue", "green", "yellow", "white", "purple"]

    return (
        f"Today's fortune for {name}\n"
        f"Fortune: {rng.choice(levels)}\n"
        f"Lucky activity: {rng.choice(items)}\n"
        f"Lucky color: {rng.choice(colors)}\n"
        f"Lucky number: {rng.randint(1, 49)}"
    )

if __name__ == "__main__":
    mcp.run()

这里有三个关键点：

FastMCP("uranai") 创建了服务器实例。

给函数加上 @mcp.tool 就足以让它变成 Claude 可以调用的东西。

docstring（"""...""" 部分）是 AI 用来决定何时使用该工具的依据——要把写清楚。

值得注意的一个技巧是用今天的日期作为随机数生成器的种子。这样就可以免费获得算命应用的行为：同一个人在同一天再次询问会得到相同的结果，而第二天则会得到不同的结果。

从项目目录运行：

python server.py

如果启动没有报错，就可以连接到 Claude Code 了。

连接到 Claude Code

如果你还没有安装 Claude Code CLI，先安装——请参阅你平台（macOS、Linux 或 Windows）的官方安装文档。

然后注册服务器：

claude mcp add uranai -- python /path/to/server.py

将 /path/to/server.py 替换为实际路径（如果你使用的是虚拟环境，最好指向该虚拟环境的 Python 可执行文件以确保安全）。

重启或重新加载 Claude Code，uranai 服务器应该会被识别。你可以用 /mcp 命令检查连接状态。

如果你使用的是 Claude 桌面应用，将以下内容添加到配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "uranai": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/uranai/server.py"]
    }
  }
}

（在 Windows 上，command 的路径类似于 C:\\Users\\yourname\\uranai\\venv\\Scripts\\python.exe。）

打开 Claude Code，让它给你算一卦，并在出现提示时批准工具调用。你应该会得到由你自己的工具生成的运势结果。

进一步探索的方向

基础功能跑通之后，添加更多工具只需要再写一个函数并用 @mcp.tool 装饰即可：

塔罗牌/御神签模式：扩充结果和消息池以增加多样性。

基于星座的运势：把生日解析为星座，然后相应地定制结果。

外部 API 集成：接入天气或日历数据，添加一些现实世界的风味。

结果持久化：将运势历史记录到文件或数据库。

如果需求变得更重——图像生成、大规模分析——你不必非得在笔记本上运行。可以把计算负载卸载到 GPU 云实例上，然后从那里暴露 MCP 服务器。

使用 FastMCP，构建 MCP 服务器的核心就是"写一个 Python 函数，加上 @mcp.tool"。我们这里完整走了一遍整个流程——环境配置、写工具、连接到 Claude Code、确认可用——以算命工具为例。

同样的模式可以扩展到更有用的场景：包装内部工具、自动化重复任务，等等。算命只是一个入门示例——下次试试换成你自己的点子吧。

📌 本文反映了截至 2026 年 6 月的 Claude Code 行为。由于 Claude Code 更新频繁，请查看官方文档了解最新详情。

本文由 AI 辅助编辑。*最初发表于 EdgeHUB 日文版。