从零构建MCP服务器：FastMCP实战指南

引言：MCP协议与FastMCP框架

Model Context Protocol（MCP）是连接AI模型与外部服务的标准化协议，允许LLM（如Claude、Gemini）调用工具、访问数据。然而，直接实现MCP协议需要处理JSON-RPC、会话管理等繁琐细节。FastMCP作为Python框架，封装了这些底层逻辑，让开发者专注于业务功能。本文将通过分步实战，从零构建一个完整的MCP服务器，涵盖工具、资源、动态模板等核心功能。

一、环境准备：安装FastMCP

首先确保安装FastMCP框架，推荐使用pip：

bash 复制代码

pip install fastmcp

二、Step 1：创建基础服务器

所有FastMCP应用的起点是FastMCP类实例，它作为工具、资源的容器。

代码示例：

python 复制代码

# my_mcp_server.py
from fastmcp import FastMCP

# 初始化MCP服务器，指定名称（用于标识服务）
mcp = FastMCP(name="My First MCP Server")

说明：

这行代码创建了一个空的MCP服务器，暂时不包含任何功能。
名称参数（name）用于区分不同服务器，便于客户端识别。

三、Step 2：添加工具（Tools）

工具是LLM可调用的函数（如计算、数据处理），通过@mcp.tool装饰器定义。

代码示例：

python 复制代码

from fastmcp import FastMCP

mcp = 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。

代码示例：

python 复制代码

@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}）会映射为函数参数。

代码示例：

python 复制代码

@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）。

完整代码：

python 复制代码

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

启动命令：

bash 复制代码

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提供更强大的外部能力。