/ 目录 / 演练场 / FastMCP
← 全部服务器 ↗ GitHub
● 官方 PrefectHQ ⚡ 即开即用

FastMCP

作者 PrefectHQ · PrefectHQ/fastmcp

用 Python 的方式构建 MCP 服务器的正确打开方式——装饰一个函数，得到一个工具。20 行代码搞定一个 MCP。

FastMCP 是一个用于构建 MCP 服务器的 Python 框架（不是一个需要安装的服务器）。一个 @mcp.tool 装饰器就能把一个有类型注解的函数转换成 MCP 工具，schema 会从你的注解自动推导。框架会处理 stdio/SSE 传输、生命周期和协议细节，你只需要关注业务逻辑。

▶ 观看演示 📦 安装 💡 使用场景

为什么要用

核心特性

实时演示

实际使用效果

fastmcp.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "fastmcp",
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  ]
}

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "fastmcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fastmcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add fastmcp -- uvx fastmcp

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： FastMCP

在一小时内把内部 REST API 暴露为 MCP

👤 拥有现有 Python 服务的后端工程师 ⏱ ~45 min intermediate

何时使用： 你有一个公司内部的 API，希望 agent 能调用它，又不想从头写 client spec。

前置条件
  • Python 3.10+ — python --version
  • 已安装 uv — curl -LsSf https://astral.sh/uv/install.sh | sh
步骤
  1. 初始化项目
    基于 FastMCP 搭建一个名为 'acme-api-mcp' 的服务器项目，带一个示例工具。用 uv 管理依赖。✓ 已复制
    → pyproject.toml + 带有可运行 @mcp.tool 示例的 server.py
  2. 为 3 个价值最高的端点编写包装
    我的内部 API 有 /orders/{id}、/customers/search、/invoices/{id}/pdf 这些端点。用 httpx.AsyncClient 为每一个写一个 FastMCP 工具，从环境变量读取 AUTH_TOKEN。✓ 已复制
    → 3 个有类型提示和文档字符串的装饰函数，这些字符串会变成工具描述
  3. 用 MCP Inspector 在本地测试
    用 uv run mcp dev server.py 运行服务器。打开 Inspector，用真实的输入调用每个工具。✓ 已复制
    → 工具返回预期的 JSON，没有栈跟踪

结果： 一个可用的 MCP 服务器，你可以把 Claude Desktop 或任何 MCP 客户端指向它。

注意事项
  • 因为在文档字符串中打印了凭据，导致泄露到工具描述中 — 用文档字符串描述行为，不要包含真实 token 的示例。通过 os.environ 加载凭据，在错误信息中永远不要输出它们
  • 混合使用异步和同步，导致事件循环错误 — 二选一——如果你的 HTTP 客户端是异步的，那么整个工具都要是异步的；不要在工具内部调用 asyncio.run

把公司文档作为 MCP resource 暴露给 RAG

👤 构建 agent 基础设施的平台工程师 ⏱ ~30 min intermediate

何时使用： 你希望 agent 能自动发现和拉取公司知识，而不用为每个文件都调用工具。

步骤
  1. 定义 resource 列表
    定义一个 FastMCP resource，URI 为 docs://{path}，列出 ./docs/ 下的所有 markdown 文件，读取时返回它们的内容。✓ 已复制
    → Resource 已注册，Inspector 显示列表
  2. 添加模板 resource
    添加一个 resource 模板 docs://{category}/{slug}，返回匹配的文件。文档化有效的 {category} 值。✓ 已复制
    → 模板已注册，参数化的获取工作正常
  3. 在真实客户端中测试
    把 Claude Desktop 连接到服务器。验证 Resources 菜单列出了所有文档且内容加载正常。✓ 已复制
    → Resources 显示为可附加的上下文

结果： 一个以 resource 为基础的知识库，agent 能原生地从中提取——比静态内容的工具调用更清洁。

注意事项
  • 大型 resource 列表会淹没客户端的 UI — 在列表端点中分页或过滤；不是每个文件都需要暴露出来

把 FastMCP 服务器部署为远程 SSE 端点

👤 为多个团队服务的平台工程师 ⏱ ~60 min advanced

何时使用： 多个开发者需要同一个 MCP——托管一次，不要让每个人都在本地运行 stdio。

前置条件
  • 容器主机（Cloud Run、Fly、Railway） — 任何支持 Docker 的运行时都可以
步骤
  1. 切换传输到 SSE
    修改 server.py，运行 mcp.run(transport='sse', host='0.0.0.0', port=8080)。添加一个最小的 Dockerfile。✓ 已复制
    → 本地 curl localhost:8080/sse 显示 SSE 握手
  2. 在身份验证后部署
    用 IAM auth 部署到 Cloud Run。在 FastAPI 中间件中为 /sse 端点添加基于 header 的身份验证检查。✓ 已复制
    → 公共 URL，未授权的请求返回 401
  3. 连接客户端
    和团队成员分享连接命令：npx -y mcp-remote https://mcp.acme.com/sse。验证他们的 Claude Desktop 能识别这些工具。✓ 已复制
    → 团队成员的客户端看到相同的工具

结果： 一个共享的远程 MCP——一份代码库，众多用户，易于更新。

注意事项
  • 在某些企业代理后面 SSE 连接会断开 — 改用 streamable HTTP 传输（更新的规范）或文档化 VPN/直连的需求
搭配使用： cloud-run

组合

与其他 MCP 搭配，撬动十倍杠杆

fastmcp + cloud-run

编写一次，部署到 Cloud Run，与团队共享

把我的内部定价 API 包装成 FastMCP 服务器，容器化它，然后用 IAM auth 部署到 Cloud Run。✓ 已复制
fastmcp + fastapi-mcp

比较方法——FastMCP 用于新项目，fastapi-mcp 用于现有 FastAPI 应用

我有一个现有的 FastAPI 服务。我应该添加 fastapi-mcp 来暴露它，还是用 FastMCP 重写？根据我的路由进行比较。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
@mcp.tool decorated function with typed signature 把任何你想让 agent 调用的函数包装起来 free
@mcp.resource URI template + function 暴露可读的内容（文档、配置、数据快照） free
@mcp.prompt decorated function returning Message[] 为客户端提供可复用的多轮 prompt 模板 free
mcp.run transport: 'stdio'|'sse'|'streamable-http', host?, port? 入口点——在 main 脚本末尾调用 free
Context (ctx) parameter inject ctx: Context into any tool 需要流式传输进度或日志的长时间运行工具 free

成本与限制

运行它的成本

API 配额
无——这是一个框架，不是一个服务
每次调用 Token 数
你的服务器运行任何 LLM 调用；框架开销可以忽略不计
费用
免费，开源
提示
对于静态内容，用 resource 而不是 tool——resource 在 token 上更便宜，因为它们是提前声明的

安全

权限、密钥、影响范围

凭据存储： 你的选择——环境变量是惯用的；在进程启动时加载凭据，而不是每次调用都加载
数据出站： 你的工具函数调用的任何地方

故障排查

常见错误与修复

工具 schema 在客户端中缺少必需字段

你的函数参数需要类型提示。简单的 def foo(x) 会生成无用的 schema——用 def foo(x: str) 加上文档字符串。

验证： 运行 `uv run mcp dev server.py` 并检查 Inspector 的工具 schema
服务器启动但客户端看不到工具

你混淆了 stdio 和 SSE 的配置。对于 Claude Desktop 用 transport='stdio'；对于 mcp-remote 用 'sse'。

`ImportError: No module named 'fastmcp'`

用 uv pip install fastmcp 安装，或添加到 pyproject.toml 的依赖中。检查你是否从同一个 venv 运行服务器。

验证： uv pip show fastmcp
异步工具在首次调用时挂起

你在异步工具内导入了同步 httpx。用 httpx.AsyncClient 和 async with——永远不要混合。

替代方案

FastMCP 对比其他方案

替代方案何时用它替代权衡
TypeScript MCP SDK你的团队用 TS/Node，想继续用官方维护、维护良好、开发体验相似——只是语言不同
fastapi-mcp你已经有了 FastAPI 应用，想把路由暴露为工具对 MCP 接口的控制更少，但现有服务无需重构
csharp-sdk.NET 团队官方出品，但示例生态较小

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills