FastMCP

技能简介

FastMCP 是由 Prefect 团队维护的 Python MCP 应用框架，专为快速构建 MCP 服务器、客户端和交互式应用而设计。它用普通 Python 函数声明工具，自动生成 schema、验证逻辑和文档，让开发者专注于业务逻辑而无需处理底层协议细节。FastMCP 号称"每天被下载一百万次，70% 的 MCP 服务器以某种形式运行着它"，是当前 Python 生态中最主流的 MCP 开发框架。最新版本 4.x 于 2026 年 9 月 17 日发布，带来了大量新特性和升级指南。

核心能力

• 装饰器驱动的工具注册：用 @mcp.tool 装饰器将普通 Python 函数一键暴露为 MCP 工具，自动生成输入输出 schema，无需手动编写 JSON Schema
• 多传输协议支持：内置 stdio 和 Streamable HTTP 两种传输方式，连接远程服务器时自动处理传输协商和身份验证
• 完整客户端能力：FastMCP.Client 可连接任意 MCP 服务器，高级 API 支持重试、超时、流式处理
• 交互式应用（Apps）：在对话中直接渲染工具的交互式 UI，终端用户无需编写代码即可使用复杂工具
• 标准 Schema 集成：使用 Standard Schema（支持 Zod v4、Valibot、ArkType 等），灵活选择验证库
• 丰富的中间件生态：官方提供 Express、Fastify、Hono、Node.js HTTP 等框架适配层
• 企业级扩展：配套产品 Prefect Horizon 提供 MCP 网关、SSO、工具级 RBAC、审计日志等企业功能
• TypeScript 对应实现：同一团队维护的 @prefecthq/fastmcp-ts 提供 TypeScript 原生支持

安装配置

前置要求：Python 3.10+，推荐使用 uv 包管理器

方式一：使用 uv（推荐）

uv add fastmcp

方式二：使用 pip

pip install fastmcp

方式三：从源码安装

git clone https://github.com/PrefectHQ/fastmcp.git
cd fastmcp
uv sync

安装完成后，验证版本：

python -c "import fastmcp; print(fastmcp.__version__)"

使用步骤

第一步：创建 MCP 服务器

from fastmcp import FastMCP

mcp = FastMCP("My Server")

@mcp.tool
def add(a: int, b: int) -> int:
    """将两个数字相加"""
    return a + b

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

第二步：通过 stdio 连接到 Claude Code

在 Claude Code 中注册 MCP 服务器：

claude mcp add fastmcp -- npx -y fastmcp

或直接运行服务器：

python my_server.py

第三步：构建客户端连接

from fastmcp import FastMCP

async def main():
    async with FastMCP("Client") as client:
        # 连接远程服务器
        await client.connect("http://localhost:8000/mcp")
        # 调用工具
        result = await client.call_tool("add", {"a": 3, "b": 5})
        print(result)

import asyncio
asyncio.run(main())

第四步：构建带交互式 UI 的 App

@mcp.tool
def show_chart(data: list[dict]) -> str:
    """渲染数据图表"""
    return mcp.render.ui(data)

适用场景

• AI 助手能力扩展：为 Claude、GPT 等 LLM 添加自定义工具（网页搜索、数据库查询、文件处理等），实现更深度的任务自动化
• 数据管道与 ETL：快速将 Python 数据处理函数封装为 MCP 工具，供 AI 代理调用执行复杂的数据转换和分析任务
• 内部工具平台：用 FastMCP 构建企业内部工具集，通过 MCP 协议统一暴露给所有 AI 代理，支持权限控制和审计
• Agent 工作流编排：配合 Prefect 本身的流程编排能力，构建包含人工审批、条件分支、并行执行等复杂逻辑的 AI Agent 工作流
• 测试与验证：在 CI/CD 中用 FastMCP 快速搭建测试用 MCP 服务器，验证 AI 代理的工具调用行为
• 教育与原型开发：用几行代码即可快速验证 MCP 协议能力，适合教学演示和产品原型阶段

适用人群

• Python 后端开发者：已有 Python 技能树，希望快速为 AI 代理添加自定义工具
• AI 应用工程师：构建基于 LLM 的应用，需要统一、可复用的工具调用层
• 数据工程师/科学家：将数据处理逻辑暴露为 AI 可调用的工具，实现 AI 驱动的数据分析
• 平台工程师：构建企业内部 AI 工具平台，统一管理工具权限和使用审计
• 全栈开发者：需要同时维护前后端和 AI 能力，希望用同一套 Python 代码同时服务多种客户端

工作原理

FastMCP 的核心设计理念是"最佳实践内置，开发者专注逻辑"。当开发者用 @mcp.tool 装饰一个 Python 函数时，FastMCP 自动完成以下工作：

1. Schema 生成：分析函数签名（参数类型、返回值类型）和 docstring，自动生成 MCP 协议所需的 tool inputSchema 和描述
2. 协议封装：将函数调用结果封装为 MCP 规范的 JSON-RPC 响应格式，处理错误序列化
3. 传输抽象：开发者无需关心是 stdio 还是 HTTP，FastMCP 自动处理传输层细节
4. 客户端代理：FastMCP.Client 维护与服务器的连接池、自动重连和请求路由
5. UI 渲染：对于 Apps 功能，FastMCP 在协议层面增加了 UI 渲染指令，兼容 MCP 协议的客户端可以直接渲染

FastMCP 建立在 Model Context Protocol 规范之上（2026-07-28 版本），兼容所有主流 MCP 客户端（Claude Code、Claude.ai、Cursor、VS Code、OpenCode 等）。

官方链接

• PyPI：https://pypi.org/project/fastmcp/
• 文档：https://gofastmcp.com
• GitHub：https://github.com/PrefectHQ/fastmcp
• Discord 社区：https://discord.gg/uu8dJCgttd
• TypeScript 版本：https://github.com/PrefectHQ/fastmcp-ts
• Prefect Horizon（企业版）：https://www.prefect.io/horizon