如何快速构建使用FastMCP：Model Context Protocol服务器从零开始实战指南

FastMCP是一个基于Python的Model Context Protocol（MCP）服务器框架，它提供了简洁的装饰器API，帮助开发者快速构建能与LLM（大型语言模型）集成的后端服务。作为Python框架，FastMCP特别适合需要为AI应用提供结构化资源和工具调用能力的场景，让LLM能够通过标准化协议访问外部功能。

场景价值：为什么选择FastMCP构建MCP服务器

在AI应用开发中，大型语言模型常需要访问外部数据或工具才能完成复杂任务。FastMCP解决了这一核心痛点，它像"AI应用的翻译官"，让LLM能够通过标准化接口无缝调用开发者提供的资源和工具。无论是构建智能客服需要的知识库查询，还是开发AI助手所需的函数调用能力，FastMCP都能提供简单而强大的解决方案。

核心特性：FastMCP的三大优势

FastMCP之所以成为构建MCP服务器的理想选择，源于其三大核心特性：

极简API设计

通过直观的装饰器模式，开发者只需几行代码就能将普通Python函数转换为LLM可访问的资源和工具，大幅降低集成门槛。

异步性能优化

基于ASGI服务器（异步网关接口，用于处理并发请求）构建，能高效处理大量并发请求，确保AI应用的响应速度。

灵活扩展能力

支持多种认证方式、工具转换和命名空间管理，可轻松扩展以满足复杂业务需求。

环境准备：5分钟环境初始化

在开始使用FastMCP前，请确保你的开发环境满足以下要求：

• Python 3.7或更高版本
• pip包管理工具

安装FastMCP及依赖

首先克隆项目仓库到本地：

git clone https://gitcode.com/GitHub_Trending/fa/fastmcp
cd fastmcp

然后使用pip安装FastMCP及其依赖：

pip install -e .

💡 技巧：使用-e参数以开发模式安装，便于后续修改源码时无需重新安装。

验证安装

安装完成后，运行以下命令验证是否安装成功：

fastmcp --version

如果安装成功，你将看到类似以下的输出：

fastmcp, version 0.1.0

⚠️ 警告：如果提示"fastmcp: command not found"，请检查Python的Scripts目录是否已添加到系统PATH。

分步实战：三步完成基础MCP服务器构建

第一步：创建基础服务器

创建一个名为my_mcp_server.py的文件，输入以下代码：

from fastmcp import FastMCP

# 初始化MCP服务器实例
mcp = FastMCP(server_name="MyFirstMCP")

# 定义一个简单的资源
@mcp.resource(namespace="demo", name="welcome")
def get_welcome_message():
    """返回欢迎消息的资源"""
    return {"message": "欢迎使用FastMCP构建的MCP服务器", "version": "1.0"}

# 定义一个基础工具
@mcp.tool(namespace="calculator", name="add_numbers")
def add_numbers(a: float, b: float) -> float:
    """两数相加的工具
    
    Args:
        a: 第一个数字
        b: 第二个数字
        
    Returns:
        两数之和
    """
    return a + b

if __name__ == "__main__":
    # 启动服务器，默认端口8000
    mcp.run(debug=True)

第二步：运行MCP服务器

在终端中执行以下命令启动服务器：

python my_mcp_server.py

成功启动后，你将看到类似以下的输出：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12347]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

第三步：测试MCP服务器功能

打开新的终端窗口，使用curl命令测试资源：

curl http://127.0.0.1:8000/resources/demo/welcome

你应该会得到以下响应：

{"message": "欢迎使用FastMCP构建的MCP服务器", "version": "1.0"}

测试工具调用：

curl -X POST http://127.0.0.1:8000/tools/calculator/add_numbers \
  -H "Content-Type: application/json" \
  -d '{"a": 5, "b": 3}'

响应应该是：

8.0

注意事项：如果遇到连接被拒绝的错误，请检查服务器是否正在运行，以及端口是否正确。默认情况下，FastMCP使用8000端口，如果该端口已被占用，可以通过mcp.run(port=8001)指定其他端口。

常见问题：解决实战中的痛点

服务器启动后无法访问

如果服务器启动成功但无法通过浏览器或curl访问，请检查：

1. 防火墙设置是否阻止了端口访问
2. 是否在服务器启动时指定了非默认IP（如--host 0.0.0.0）
3. 网络环境是否允许本地连接

工具参数验证失败

FastMCP使用Pydantic进行参数验证，如果遇到参数错误：

1. 检查请求的JSON格式是否正确
2. 确认参数类型与工具定义一致（如数字类型不要传字符串）
3. 使用fastmcp validate命令验证工具定义

如何处理跨域请求

在创建FastMCP实例时添加CORS配置：

mcp = FastMCP(
    server_name="MyFirstMCP",
    cors_allowed_origins=["https://your-frontend-domain.com"]
)

扩展方向：从基础到高级应用

高级认证配置

FastMCP支持多种认证方式，包括OAuth、Bearer Token等。详细配置方法请参考官方文档：docs/servers/auth/authentication.mdx

多服务器组合

通过挂载多个MCP服务器实现功能模块化：

from fastmcp import FastMCP
from other_server import another_mcp

main_mcp = FastMCP("MainServer")
main_mcp.mount("/other", another_mcp)

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

工具转换与版本控制

使用工具转换功能实现API版本管理和请求转换：

@mcp.tool_transform
def version_transform(tool, request):
    if request.query_params.get("version") == "v2":
        # 转换请求参数以兼容v2版本API
        request.data["new_param"] = request.data.pop("old_param")
    return tool, request

扩展阅读

• 官方高级功能文档：docs/advanced.md
• 完整API参考：docs/python-sdk/
• 示例项目集合：examples/

通过本指南，你已经掌握了FastMCP的基本使用方法。这个强大的Python框架将帮助你轻松构建与LLM集成的MCP服务器，为AI应用提供丰富的资源和工具支持。无论是构建简单的演示项目还是复杂的生产系统，FastMCP都能为你提供高效而灵活的解决方案。