从零构建MCP服务器:FastMCP实战指南
引言:MCP协议与FastMCP框架
Model Context Protocol(MCP)是连接AI模型与外部服务的标准化协议,允许LLM(如Claude、Gemini)调用工具、访问数据。然而,直接实现MCP协议需要处理JSON-RPC、会话管理等繁琐细节。FastMCP作为Python框架,封装了这些底层逻辑,让开发者专注于业务功能。本文将通过分步实战,从零构建一个完整的MCP服务器,涵盖工具、资源、动态模板等核心功能。
一、环境准备:安装FastMCP
首先确保安装FastMCP框架,推荐使用pip:
pip install fastmcp
二、Step 1:创建基础服务器
所有FastMCP应用的起点是FastMCP
类实例,它作为工具、资源的容器。
代码示例:
# my_mcp_server.py
from fastmcp import FastMCP# 初始化MCP服务器,指定名称(用于标识服务)
mcp = FastMCP(name="My First MCP Server")
说明:
- 这行代码创建了一个空的MCP服务器,暂时不包含任何功能。
- 名称参数(
name
)用于区分不同服务器,便于客户端识别。
三、Step 2:添加工具(Tools)
工具是LLM可调用的函数(如计算、数据处理),通过@mcp.tool
装饰器定义。
代码示例:
from fastmcp import FastMCPmcp = FastMCP(name="My First MCP Server")@mcp.tool
def add(a: int, b: int) -> int:"""Adds two integer numbers together."""return a + b
FastMCP自动处理的细节:
- 工具名称:默认使用函数名(如
add
)。 - 描述:从函数文档字符串(docstring)提取,供LLM理解用途。
- 输入 schema:通过类型注解(
a: int
、b: int
)生成JSON schema,确保LLM传入正确类型的参数。
优势:无需手动定义协议格式,专注函数逻辑即可。
四、Step 3:添加静态资源(Resources)
资源是LLM可访问的只读数据(如配置、知识库),通过@mcp.resource
装饰器定义,并绑定唯一URI。
代码示例:
@mcp.resource("resource://config")
def get_config() -> dict:"""Provides the application's configuration."""return {"version": "1.0", "author": "MyTeam"}
说明:
- URI:
resource://config
是资源的唯一标识,客户端通过该路径访问。 - 懒加载:函数
get_config
仅在客户端请求时执行,避免不必要的计算。 - 返回格式:支持字典、字符串等,FastMCP自动序列化为JSON返回给客户端。
五、Step 4:添加动态资源模板(Resource Templates)
资源模板允许通过URI参数生成动态内容,URI中的占位符(如{name}
)会映射为函数参数。
代码示例:
@mcp.resource("greetings://{name}")
def personalized_greeting(name: str) -> str:"""Generates a personalized greeting for the given name."""return f"Hello, {name}! Welcome to the MCP server."
使用方式:
- 客户端请求
greetings://Alice
时,FastMCP自动调用personalized_greeting(name="Alice")
,返回"Hello, Alice!..."
。 - 占位符与函数参数名必须一致(如
{name}
对应name: str
),支持多个参数(如greetings://{name}/{title}
)。
六、Step 5:运行服务器
通过mcp.run()
启动服务器,默认使用STDIO传输(适合本地客户端如Claude Desktop)。
完整代码:
from fastmcp import FastMCP# 1. 初始化服务器
mcp = FastMCP(name="My First MCP Server")# 2. 添加工具
@mcp.tool
def add(a: int, b: int) -> int:"""Adds two integer numbers together."""return a + b# 3. 添加静态资源
@mcp.resource("resource://config")
def get_config() -> dict:"""Provides the application's configuration."""return {"version": "1.0", "author": "MyTeam"}# 4. 添加动态资源模板
@mcp.resource("greetings://{name}")
def personalized_greeting(name: str) -> str:"""Generates a personalized greeting for the given name."""return f"Hello, {name}! Welcome to the MCP server."# 5. 启动服务器
if __name__ == "__main__":mcp.run()
启动命令:
python my_mcp_server.py
传输方式扩展:
- 默认STDIO传输适用于本地客户端。
- 如需HTTP服务,可通过
mcp.http_app()
创建ASGI应用,搭配uvicorn运行(详见FastMCP部署文档)。
七、服务器功能验证
客户端(如Claude Desktop)可通过以下方式交互:
- 调用工具:请求调用
add
工具,传入a=3
、b=5
,返回8
。 - 访问静态资源:请求
resource://config
,返回配置字典。 - 访问动态资源:请求
greetings://Bob
,返回"Hello, Bob!..."
。
八、总结:FastMCP的核心优势
- 极简开发:用Python函数+装饰器定义工具和资源,无需关注协议细节。
- 自动适配:自动生成schema、处理序列化,确保与MCP客户端兼容。
- 灵活扩展:支持静态资源、动态模板、多传输方式(STDIO/HTTP)。
通过本文的步骤,你已构建了一个功能完整的MCP服务器。后续可扩展更复杂的工具(如数据库查询、API调用)和资源(如实时数据),为LLM提供更强大的外部能力。