一、FastMCP 是个啥？白话解释

FastMCP 是一个Python 框架，专门用来快速搭建MCP 服务器和客户端。MCP 全称Model Context Protocol（模型上下文协议），简单说就是大模型和外部世界沟通的标准化语言。

想象一下：大模型是个聪明的大脑，但它自己没手没脚，没法查天气、算数据、控制设备。MCP 就像给大脑装了个标准化的 "接口"，让它能安全、规范地调用外部工具和获取数据；而 FastMCP 就是这个接口的 "快速搭建工具包"，让你不用懂复杂的协议细节，几行 Python 就能搞定。

核心作用：

• 让大模型能调用函数 / 工具（比如计算器、API、自动化脚本）
• 让大模型能获取结构化数据（比如用户信息、实时行情、配置参数）
• 提供安全的通信方式（权限控制、数据验证）
• 标准化接口，一次开发，多个大模型都能用

二、快速上手：3 分钟搭个 MCP 服务器

1. 安装 FastMCP（30 秒）

打开命令行，输入以下命令（二选一，推荐用 uv 更快）：

# 方法1：用pip安装
pip install fastmcp

# 方法2：用uv安装（更快，推荐）
uv pip install fastmcp

2. 第一个 MCP 服务器：计算器 + 问候语（2 分钟）

创建文件my_server.py，复制以下代码：

# 从fastmcp库导入核心类
from fastmcp import FastMCP

# 1. 初始化MCP服务器实例（起个名字）
mcp = FastMCP(name="我的第一个MCP服务器", description="能算加减、会打招呼的服务器")

# 2. 注册工具（大模型能调用的函数，类似POST接口）
# 用@mcp.tool装饰器，把普通函数变成MCP工具
@mcp.tool
def add(a: int, b: int) -> int:
    """加法运算：计算两个整数的和"""  # 文档字符串会自动变成工具描述，给大模型看
    return a + b

@mcp.tool
def subtract(a: int, b: int) -> int:
    """减法运算：计算两个整数的差"""
    return a - b

@mcp.tool
def greet(name: str, language: str = "zh") -> str:
    """根据姓名和语言生成问候语
    参数:
        name: 要问候的人名字
        language: 语言（zh中文，en英文，默认中文）
    """
    greetings = {
        "zh": f"你好，{name}！欢迎使用FastMCP服务器~",
        "en": f"Hello, {name}! Welcome to FastMCP server~"
    }
    return greetings.get(language, "你好，朋友！")  # 语言不存在时的默认值

# 3. 注册资源（大模型能获取的数据，类似GET接口）
# 用@mcp.resource装饰器，定义资源路径
@mcp.resource("system_info")  # 资源路径：system_info
def get_system_info() -> dict:
    """获取服务器系统信息"""
    return {
        "server_name": "我的第一个MCP服务器",
        "version": "1.0",
        "functions": ["add", "subtract", "greet"],
        "resources": ["system_info"]
    }

@mcp.resource("greeting://{name}")  # 动态资源路径：greeting://张三
def get_personalized_greeting(name: str) -> str:
    """获取个性化问候语（通过路径参数）"""
    return f"欢迎你，{name}！这是专属你的问候~"

# 4. 启动服务器（默认端口8000）
if __name__ == "__main__":
    mcp.run(port=8000, reload=True)  # reload=True：代码修改后自动重启，方便调试

3. 启动服务器（10 秒）

命令行输入：

python my_server.py

看到类似这样的输出就成功了：

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

三、核心概念：工具 (Tool) vs 资源 (Resource)（白话理解）

概念	白话解释	类比	装饰器
工具 (Tool)	大模型能主动调用的功能，会产生计算或副作用	像手机里的 APP（计算器、拍照）	@mcp.tool
资源 (Resource)	大模型能获取的静态 / 动态数据，一般不改变系统状态	像手机里的相册、通讯录	@mcp.resource("路径")

关键区别：

• 工具：需要大模型传参数，执行后返回结果（比如算 1+1）
• 资源：可以通过路径直接访问，获取数据（比如查系统信息）

FastMCP 会自动帮你做这些事：

1. 生成工具 / 资源的描述（给大模型看）
2. 验证输入参数的类型（防止传错数据）
3. 处理网络通信和协议封装（不用你写 HTTP 接口）
4. 提供标准的 MCP 协议响应格式

四、客户端怎么用？和大模型交互（完整示例）

服务器搭好了，怎么让大模型用它？这里写一个 Python 客户端示例，模拟大模型调用过程：

1. 客户端代码（my_client.py）

import asyncio
from fastmcp import Client
from fastmcp.client.transports import SSETransport  # 用SSE协议通信（常用）

async def main():
    # 1. 连接到本地MCP服务器
    transport = SSETransport("http://localhost:8000/mcp")
    async with Client(transport) as client:
        
        print("=== 1. 获取资源：system_info ===")
        system_info = await client.get_resource("system_info")
        print("服务器信息：", system_info)
        
        print("\n=== 2. 获取动态资源：greeting://豆包 ===")
        greeting = await client.get_resource("greeting://豆包")
        print("个性化问候：", greeting)
        
        print("\n=== 3. 调用工具：add(10, 20) ===")
        add_result = await client.call_tool("add", a=10, b=20)
        print("10+20 =", add_result)
        
        print("\n=== 4. 调用工具：greet(豆包, en) ===")
        greet_result = await client.call_tool("greet", name="豆包", language="en")
        print("英文问候：", greet_result)
        
        print("\n=== 5. 调用工具：subtract(50, 15) ===")
        subtract_result = await client.call_tool("subtract", a=50, b=15)
        print("50-15 =", subtract_result)

# 运行客户端
if __name__ == "__main__":
    asyncio.run(main())

2. 运行客户端（确保服务器已启动）

命令行输入：

python my_client.py

预期输出：

=== 1. 获取资源：system_info ===
服务器信息： {'server_name': '我的第一个MCP服务器', 'version': '1.0', 'functions': ['add', 'subtract', 'greet'], 'resources': ['system_info']}

=== 2. 获取动态资源：greeting://豆包 ===
个性化问候： 欢迎你，豆包！这是专属你的问候~

=== 3. 调用工具：add(10, 20) ===
10+20 = 30

=== 4. 调用工具：greet(豆包, en) ===
英文问候： Hello, 豆包! Welcome to FastMCP server~

=== 5. 调用工具：subtract(50, 15) ===
50-15 = 35

五、进阶玩法：给大模型用的实用工具（天气查询示例）

让我们升级服务器，添加一个能查天气的工具（用 requests 库调用公开 API）：

1. 安装依赖

pip install requests  # 用于发送HTTP请求

2. 升级后的服务器代码（weather_server.py）

from fastmcp import FastMCP
import requests  # 新增：导入requests库

mcp = FastMCP(name="天气查询服务器", description="能查全球天气的MCP服务器")

# 新增：天气查询工具
@mcp.tool
def get_weather(city: str, unit: str = "c") -> dict:
    """查询指定城市的天气
    参数:
        city: 城市名称（如北京、上海、New York）
        unit: 温度单位（c=摄氏度，f=华氏度，默认摄氏度）
    返回:
        包含天气状况、温度、湿度等信息的字典
    """
    try:
        # 调用公开天气API（这里用的是wttr.in，免费无需API Key）
        url = f"https://wttr.in/{city}?format=j1"  # j1表示返回JSON格式
        response = requests.get(url, timeout=10)
        response.raise_for_status()  # 抛出HTTP错误
        data = response.json()
        
        # 解析天气数据
        current_condition = data["current_condition"][0]
        temp_c = int(current_condition["temp_C"])
        temp_f = int(current_condition["temp_F"])
        weather_desc = current_condition["weatherDesc"][0]["value"]
        humidity = current_condition["humidity"]
        
        # 根据单位返回结果
        if unit == "f":
            temp = temp_f
            unit_str = "°F"
        else:
            temp = temp_c
            unit_str = "°C"
        
        return {
            "city": city,
            "weather": weather_desc,
            "temperature": f"{temp}{unit_str}",
            "humidity": f"{humidity}%",
            "unit": unit
        }
    except Exception as e:
        return {"error": f"查询天气失败：{str(e)}"}

# 启动服务器
if __name__ == "__main__":
    mcp.run(port=8000, reload=True)

3. 客户端调用天气工具

修改客户端代码，添加：

print("\n=== 6. 调用工具：get_weather(北京) ===")
weather_result = await client.call_tool("get_weather", city="北京")
print("北京天气：", weather_result)

运行后就能看到北京的实时天气了！

六、常见问题与调试技巧（白话版）

1. 服务器启动失败？

• 检查端口 8000 是否被占用（换个端口：mcp.run(port=8080)）
• 确保 FastMCP 版本正确（pip install --upgrade fastmcp）
• 检查 Python 版本（推荐 3.9+）

2. 客户端连接失败？

• 先确认服务器已启动（看控制台输出）
• 检查 URL 是否正确（http://localhost:8000/mcp）
• 关闭防火墙或允许 Python 访问网络

3. 大模型不会调用工具？

• 确保工具函数有详细的文档字符串（大模型靠这个理解工具用途）
• 类型注解要完整（比如a: int，不要写a）
• 用fastmcp dev server.py命令启动开发模式，查看工具描述是否正确

4. 怎么让 Claude / 豆包等大模型用我的服务器？

• 在大模型的设置里找到 "MCP 服务器" 或 "工具集成" 选项
• 输入服务器地址：http://localhost:8000/mcp（本地）或公网 IP + 端口（远程）
• 大模型会自动发现你的工具和资源，就能直接调用了

七、总结：FastMCP 的核心价值

FastMCP 让你用 Python 写普通函数，就能给大模型提供工具和数据，不用懂复杂的协议细节。它的核心优势是：

1. 简单：装饰器 + 类型注解，几行代码搞定
2. 标准化：遵循 MCP 协议，兼容所有支持 MCP 的大模型
3. 高效：自动处理类型验证、协议封装、网络通信
4. 灵活：支持工具、资源、提示等多种交互方式

现在你已经掌握了 FastMCP 的基本用法，可以开始给大模型开发专属工具了！比如：

• 连接数据库查数据
• 控制智能家居设备
• 自动化办公流程
• 调用企业内部 API