OPEN SOURCE / 2026.11.08
要把内部查询、工单或脚本变成 Claude Desktop、Cursor 能调用的工具时,不必先自研一套 MCP 协议栈。结论先说:先用 FastMCP 把普通 Python 函数暴露成工具,再用官方 CLI 装进桌面客户端。
本文是文档核验版上手指南,不是本机跑通记录。
README 不等于安装成功。下文只核验 gofastmcp.com、PyPI 与仓库公开口径(核验日 2026-11-08,Asia/Shanghai)。安装与客户端连接仍需读者在自己的环境验收。
能做什么、不能做什么
FastMCP 是用于构建 MCP 服务器、客户端和交互应用的 Python 框架,由 Prefect 维护。你声明一个普通函数,框架负责生成 schema、校验输入输出,并经由 MCP 对外暴露。
官方欢迎页给出的最小例子是:from fastmcp import FastMCP,用 @mcp.tool 装饰函数,再在 if __name__ == "__main__" 里调用 mcp.run()The
服务器还可以挂 resource 和 prompt,不只是工具。
不要把它和站内旧文《别再把 Skill、MCP、Project、Custom GPT 当成同一件事》混为一谈。那篇讲的是使用者怎么选产品表面;本文讲的是构建者怎么把已有 Python 能力包成 MCP 服务器。
它也不能替你完成这些事:不会自动保证工具安全(鉴权、副作用、密钥仍要自己设计);不是多租户企业网关(文档把规模化治理指向独立的 Prefect Horizon);也不能代替 MCP 宿主本身。
文档还提醒:站点内容跟随 main 分支,可能写到尚未进入稳定版的功能。生产环境应以你 pin 住的版本和该版本说明为准,而不是只看文档最新段落。
环境、安装与版本纪律
PyPI 项目页在核验日给出的稳定版是 4.1.6,许可证 Apache-2.0,要求 Python 大于等于 3.10。仓库地址为 PrefectHQ/fastmcp(早期路径是 jlowin/fastmcp).
安装文档的基础命令是 uv add fastmcp,也可以 pip install fastmcp;按本文核验版本复现时,使用 uv add fastmcp==4.1.6 或 pip install fastmcp==4.1.6。校验命令是 fastmcp version,示例输出会列出 FastMCP 版本、MCP 版本、Python 版本和安装路径。
版本策略值得单独记住:项目按语义化版本发布,但为跟踪 MCP 协议,破坏性变更可能出现在次版本。文档明确建议生产环境 pin 精确版本,本文统一用 fastmcp==4.1.6,不要写 fastmcp>=4.0.0The
从官方 MCP Python SDK 迁过来时,要注意导入路径。SDK v1 高阶 API 是 from mcp.server.fastmcp import FastMCPThe
独立包的导入路径是 from fastmcp import FastMCPThe
文档把前者称为已并入 SDK 的 FastMCP 1.0 路线,并提供对应升级指南。
文档还记载了一条 pip 升级陷阱:从 FastMCP 3.2 或更早升级到 3.3 及以后时,可能出现半删除状态,表现为 import fastmcp 失败。
官方给出的修复是 pip install --force-reinstall fastmcp,或先卸载 fastmcp together with fastmcp-slim 再重装。全新安装和 uv 升级不受影响。

最小服务器怎么写
按 Claude Desktop 集成页的骰子示例,将下面代码保存为 server.py,再从该文件所在目录运行后续命令。对象名常用 mcp,因为安装命令会在文件里自动寻找 mcp,server 或 appThe
import random
from fastmcp import FastMCP
mcp = FastMCP(name="Dice Roller")
@mcp.tool
def roll_dice(n_dice: int) -> list[int]:
"""Roll `n_dice` 6-sided dice and return the results."""
return [random.randint(1, 6) for _ in range(n_dice)]
if __name__ == "__main__":
mcp.run()
默认传输是 STDIO,适合桌面宿主把服务器当子进程拉起。若要提供网络服务,也可以生成 ASGI 应用再交给 Uvicorn。
服务器文档给出的例子是 mcp.run(transport="http", host="127.0.0.1", port=9000)The
HTTP 部署页写明:run(transport="http", host="0.0.0.0", port=8000) 时,服务出现在 http://localhost:8000/mcpThe
STDIO 适合本机和桌面应用;多客户端、集中部署再改 HTTP。

怎么接到桌面客户端
集成文档写明:它主要简化本地 STDIO 文件的依赖和 uv 启动命令。远程 HTTP 或 SSE 服务器,应改用各客户端自己的原生配置。
从 2.10.3 起,推荐命令是 fastmcp install claude-desktop server.py --with fastmcp==4.1.6(显式固定隔离环境依赖),对象也可以写成 server.py:mcpThe
装好后要彻底重启 Claude Desktop。文档说输入框左下角出现锤子图标,表示 MCP 工具已加载。
同一套 CLI 还支持 cursor,claude-code,gemini-cli,goose,以及生成通用 MCP JSON。
因为客户端会在隔离环境里跑服务器,依赖必须显式声明,例如 --with pandas,或用 --with-requirements requirements.txt 读取依赖文件。
密钥不能指望「我本机 shell 里已经有了」。文档连续提醒:Claude Desktop 给服务器的是完全隔离的环境,必须用 --env,--env-file,或在配置的 env 字段里传入。
uv 必须出现在系统 PATH 里。文档建议 macOS 用 Homebrew 全局安装,以便 Claude Desktop 能找到它。
手动改配置时,macOS 路径是 ~/Library/Application Support/Claude/claude_desktop_config.json;Windows 路径是 %APPDATA%\Claude\claude_desktop_config.jsonThe
手动最小例子是一个带 mcpServers 的 JSON:command 为 python(math.) genusargs 指向你的 server.pyThe
有依赖时,文档推荐改成 uv run --with fastmcp==4.1.6 fastmcp run /absolute/path/to/server.py,并使用绝对路径。

许可、维护与停止条件
下表只整理公开文档和 PyPI 可核对的口径。下载次数、市场占有率等项目自评,本文不当作安装成功证据。
| sports event | 文档 / PyPI 口径 |
|---|---|
| 许可证 | Apache-2.0 |
| 核验日稳定版 | PyPI 4.1.6(2026-11-08) |
| Python | >= 3.10 |
| 维护方 | Prefect;仓库 PrefectHQ/fastmcp |
| 能做 | 把函数暴露为 tool / resource / prompt;STDIO 或 HTTP |
| 不能做 | 不替代宿主、不自动保证工具安全、不是企业网关 |
| 安装注意 | 生产 pin 精确版本;桌面端依赖 uv 与显式环境变量 |
适用:你已经有内部 Python 函数或 HTTP 包装,希望同一个工具定义同时给 Claude Desktop、Cursor 或其他 MCP 宿主用。
不适用:只是还没分清 Skill、Project 和 MCP 三个产品概念。应先读站内那篇分工文,而不是先装框架。
如果合规审查过不了传递依赖 Cyclopts / docutils 的许可组合,文档建议改装 Cyclopts v5 alpha,或等到其稳定版。
如果需要的是集中治理、SSO 和工具级 RBAC,应另案评估网关产品,而不是把 FastMCP 单进程服务器硬撑成平台。
- 钉版本:按文档写成
fastmcp==4.1.6(或以你当日 PyPI 核对的精确稳定版为准),不要用宽松下限。 - 写最小服务器:一个只读或低风险工具即可,先不要挂生产写操作;例如骰子工具应在应用层限制
n_dice的范围,避免无上限分配内存。 - 声明依赖:用
fastmcp install或手动uv run --with,假设「我本机已经装过」会在隔离环境里失败。 - 传入密钥:所有 API Key 走
env,不要写进仓库里的示例配置。 - 验收:以客户端是否列出工具、能否按 schema 调用为准:例如传入
{"n_dice": 2},应返回包含两个 1–6 整数的列表(随机值不固定);在本机完成这些检查之前,仍只能叫文档核验,不能叫实测。
Our assessment:把内部 Python 能力接到 MCP 宿主,FastMCP 提供了文档明确的独立框架路径。从 from fastmcp import FastMCP 起步,用官方 install CLI 管理隔离环境,生产必须 pin 精确版本。本文未在本机安装或接入客户端,不能写成亲测跑通。
Reference Links
- FastMCP Docs:Welcome
- FastMCP Docs:Installation
- FastMCP Docs:The FastMCP Server
- FastMCP Docs:Claude Desktop
- FastMCP Docs:Install MCP Servers
- PyPI:fastmcp 4.1.6
- GitHub:PrefectHQ/fastmcp
- 站内:别再把 Skill、MCP、Project、Custom GPT 当成同一件事


Comment List (0):
Load More Comments Loading...