FastMCP 快速上手：几行代码写出一个 MCP 服务器

这篇适合谁，读完能做到什么

适合想用 Python 快速写出 MCP 服务器的读者。读完你应该能安装 FastMCP，写出一个带工具的服务器，分别用 stdio 和 HTTP 运行它，用客户端调用它，并知道怎样让工具返回可视化界面，以及怎样把服务器部署到互联网上。

FastMCP 是什么

FastMCP 是用来编写 MCP 服务器的 Python 工具包。服务器是工具、资源和其他 MCP 组件的集合；创建服务器时实例化 FastMCP 类即可^[2]。

安装

推荐用 uv 安装和管理 FastMCP^[1]：

uv add fastmcp

用 pip 的话，命令是：

pip install fastmcp

fastmcp[tasks] 之类的可选扩展用引号包起来安装，例如 pip install "fastmcp[tasks]" 会加装后台任务功能^[1]。需要返回可视化界面的话，还要装 apps 扩展：pip install "fastmcp[apps]"^[2]。

装完后运行 fastmcp version 检查，输出会列出 FastMCP 版本、MCP 版本、Python 版本和平台^[1]。

第一步：创建服务器

新建 my_server.py，写入下面的代码^[2]：

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

这时服务器还没有任何功能，下一步给它加一个工具。

第二步：加一个工具

用 @mcp.tool 装饰一个函数，就把它注册为服务器的工具^[2]。下面的 greet 接收一个名字，返回问候语^[2]：

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

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

第三步：运行服务器

mcp.run() 用来运行服务器。本地使用 stdio，远程访问使用 http^[2]。stdio 是连接 MCP 服务器与客户端的传统方式，HTTP 则支持远程连接^[2]。

用 stdio 运行时，直接执行 python my_server.py 即可^[2]。要改用 HTTP，把运行语句换成下面的写法^[2]：

from fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

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

if __name__ == "__main__":
    mcp.run(transport="http", port=8000)

if __name__ == "__main__": 这个判断块是为了让服务器在以脚本方式执行的各种客户端中都能正常运行；只通过 FastMCP CLI 启动的话，可以省略它^[2]。

用 FastMCP CLI 启动

fastmcp run my_server.py:mcp 会以默认的 stdio 传输方式启动服务器。FastMCP CLI 不执行文件中的 __main__ 块，而是直接导入服务器对象，并按命令行给出的传输方式和参数运行^[2]。要用 HTTP，加上 --transport http --port 8000：fastmcp run my_server.py:mcp --transport http --port 8000^[2]。

第四步：用客户端调用

服务器以 HTTP 方式运行后，客户端就可以连接 http://localhost:8000/mcp。下面的代码调用 greet 工具，名字参数为 Ford^[2]：

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"))

FastMCP 的客户端是异步的，所以用 asyncio.run 来执行。async with client: 负责打开连接，块内可以连续调用任意多次^[2]。

进阶：让工具返回界面

工具默认返回文本。给装饰器加上 app=True，比如 @mcp.tool(app=True)，工具就可以返回一个 Prefab 组件，由宿主渲染成图表、表格、表单或其他可视化元素^[2]。这需要先装好 apps 扩展^[2]。写好之后，可以用 fastmcp dev apps my_server.py 在本地预览，不需要 MCP 宿主^[2]。

部署到互联网

FastMCP Gateway 是 Prefect 的 FastMCP 团队构建的企业级 MCP 平台，为 MCP 服务器提供托管、身份验证、访问控制和可观测性^[2]^[3]。个人项目可以免费使用^[2]。

部署分三步^[2]^[3]：

把 my_server.py 推送到一个 GitHub 仓库。
用 GitHub 账号登录 FastMCP Gateway。
从这个仓库新建项目，把服务器入口填为 my_server.py:mcp。

常见问题

**import fastmcp 失败怎么办？** 这种情况只出现在用 pip 从 FastMCP 3.2 或更早版本升级到 3.3 或更新版本的时候；全新安装和用 uv 升级都不受影响^[1]。先运行 pip install --force-reinstall fastmcp；不行的话，依次运行 pip uninstall -y fastmcp fastmcp-slim 和 pip install fastmcp^[1]。

从 MCP SDK 或旧版 FastMCP 迁移？ 使用 from mcp.server.fastmcp import FastMCP 的 SDK v1 服务器，通常只需改一行导入^[1]；已经基于 SDK v2 的 MCPServer 编写的，迁移主要是改名^[1]。从 FastMCP 3 升级时，大多数服务器不改代码也能运行在 4 上，不兼容的地方见升级指南^[1]。从 FastMCP 2.0 升级，则参考升级指南中完整的破坏性变更列表^[1]。

版本怎么固定？ 生产环境建议使用 lockfile，或精确指定版本，例如 fastmcp==4.0.5，而不是 fastmcp>=4.0.0^[1]。