PrefectHQ/fastmcp · 上手攻略

• 仓库：PrefectHQ/fastmcp
• 链接：https://github.com/PrefectHQ/fastmcp
• 分类：skill / agent
• 作者：Tom
• 更新：2026-07-10

这是什么

FastMCP 是构建 MCP（Model Context Protocol）服务器和客户端的 Python 框架，由 Prefect（知名工作流编排平台）维护。它让你用几行 Python 代码就能把任意函数暴露为 MCP 工具，并支持通过 STDIO 或 HTTP 两种传输方式连接 LLM。

解决什么问题： 手写 MCP 服务器要处理协议细节、JSON-RPC 通信、传输层选择、认证等大量模板代码。FastMCP 把这些全部封装，你只需写业务逻辑函数的签名和 docstring，其余 MCP 协议层面的东西自动生成。

📌 背景：FastMCP 1.0 已被合并进官方 MCP Python SDK，但独立的 FastMCP 项目仍在活跃维护，当前每日下载量超过 100 万次，据官方称所有 MCP 服务器中约 70% 运行着某种形式的 FastMCP 代码。

快速安装

# 推荐用 uv（更快更干净）
uv pip install fastmcp

# 或用 pip
pip install fastmcp

⚠️ 如果你之前装了 FastMCP 3.2 或更早版本，升级后可能遇到 import fastmcp 报错，执行 pip install --force-reinstall fastmcp 即可解决（uv 不受影响）。

如需图形化工具 UI 组件（app=True 参数），额外安装：

pip install "fastmcp[apps]"

核心用法

1. 创建 MCP 服务器（最简方式）

# my_server.py
from fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool
def greet(name: str) -> str:
    """Greet a user by name."""
    return f"Hello, {name}!"

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

只需四行，你就拥有了一个完整的 MCP 服务器。FastMCP 自动从函数签名和 docstring 生成 JSON Schema 工具描述，LLM 看到的就是一个有类型、有说明的工具。

2. 添加带 UI 的工具（交互卡片）

安装 fastmcp[apps] 后，可以用 app=True 让工具在支持 FastMCP 的客户端中渲染成交互式 UI（基于 Prefab 组件库）：

from prefab_ui.app import PrefabApp
from prefab_ui.components import Column, Heading, Text, Badge
from fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool(app=True)
def greet(name: str) -> PrefabApp:
    """Greet someone with a visual card."""
    with Column(gap=4):
        Heading(f"Hello, {name}!")
        Badge("Success", variant="success")
    return PrefabApp()

工具接收参数和普通工具完全一样，但返回值是组件树，由对话界面渲染成图表、表单等视觉元素。

3. 添加资源和提示模板

资源（只读数据）：

@mcp.resource("data://config")
def get_config() -> dict:
    return {"theme": "dark", "version": "1.0"}

提示模板（LLM 专用消息模板）：

@mcp.prompt
def analyze_data(data_points: list[float]) -> str:
    formatted = ", ".join(str(p) for p in data_points)
    return f"Please analyze these data points: {formatted}"

4. 启动服务器

方式一：代码中直接运行

# STDIO 传输（默认，本地/CLI 场景）
mcp.run()

# HTTP 传输（远程访问场景）
mcp.run(transport="http", host="127.0.0.1", port=8000)

方式二：FastMCP CLI

# STDIO 模式（忽略代码中的 mcp.run() 参数）
fastmcp run my_server.py:mcp

# HTTP 模式
fastmcp run my_server.py:mcp --transport http --port 8000

💡 CLI 方式不会执行 if __name__ == "__main__" 代码块，直接导入 server 对象并运行，适合与 MCP 客户端集成。

5. 连接 MCP 服务器（客户端）

import asyncio
from fastmcp import Client

client = Client("http://localhost:8000/mcp")

async def call_tool(name: str):
    async with client:
        result = await client.call_tool("greet", {"name": name})
        print(result)

asyncio.run(call_tool("Ford"))

客户端用法注意事项： - 客户端是异步的，需要 async with - 可以在同一个 context 中做多次调用

6. 服务器说明文档（Instructions）

给服务器加一段说明，帮助 LLM 理解如何使用：

mcp = FastMCP(
    "DataAnalysis",
    instructions="提供数据分析工具。使用 get_summary() 获取数据概览。",
)

传输方式对比

典型适用场景

1. 快速为 LLM 工具箱：把现有的 Python 函数库（数据处理、文件操作、API 调用）暴露为 MCP 工具，让 Claude/GPT 等模型直接调用
2. 构建内部知识库工具：把 RAG 管道、数据库查询包装成 MCP 资源（Resource），供 LLM 检索上下文
3. 多工具 MCP 服务器：公司内部搭建统一的 MCP Server，所有 AI 工具（代码审查、发布流程、监控告警）集中管理
4. 原型验证 MCP 协议：新工具/功能先用 FastMCP 快速原型，再按需深入定制协议层

坑与注意

⚠️ __main__ 块建议写上：使用 CLI 方式运行 fastmcp run 时，CLI 会跳过 if __name__ == "__main__" 块而直接导入 server 对象。两种方式混用时，代码块写上更安全。

⚠️ 导入报错先 force-reinstall：从 FastMCP 3.2 升级上来的用户，第一次 import 可能失败，用 pip install --force-reinstall fastmcp 解决。

⚠️ app=True 需要 fastmcp[apps]：这个 extra 不在默认依赖里，缺少时会报错。

⚠️ HTTP 传输无内置认证：直接暴露在公网的 HTTP MCP 服务器没有认证机制，生产环境建议配合反向代理（nginx/Caddy）做 TLS + 认证，或使用 Prefect Horizon（企业级 MCP 网关）管理访问。

⚠️ Python 异步风格：FastMCP 客户端是异步的，如果你想在同步代码中调用，需要用 asyncio.run() 包装。

⚠️ MCP 协议仍在演进：Anthropic 持续更新 MCP 协议，部分细节（如认证流程）尚在变化中，关注官方更新频道。

与同类对比

FastMCP 是目前 Python 生态里最快的 MCP 服务器开发方式，协议细节全部隐藏，适合快速原型到中等规模生产使用。复杂定制场景再考虑直接用 MCP Python SDK。

一句话推荐结论

要给 LLM Agent 快速添加工具调用能力？用 FastMCP，装饰器一加、函数即工具，5 行代码从零到 MCP 服务器跑起来。 每天百万次下载量已经证明了它的江湖地位。