用 FastMCP 快速为 Claude Code 构建自定义工具服务器
通过 FastMCP 装饰器在几十行 Python 代码内实现 MCP Server,使 Claude Code 能调用外部工具(如日期算命),无需手写协议底层实现。
完整中文译文
"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 日文版。