FastMCP实战案例教程

一、地图查询AI工具

1.1 项目介绍

我们将构建一个简单的地图查询服务，用户输入城市名称，大模型调用FastMCP工具，通过地理API查询该城市的经纬度，并将结果返回。

1.2 安装与环境准备

1. 创建虚拟环境（推荐）

python3 -m venv mcp-env
source mcp-env/bin/activate

1. 安装FastMCP

pip install fastmcp

1. 安装地图查询依赖（使用OpenStreetMap Nominatim API）

pip install requests

1.3 完整代码实现：地图查询工具

创建文件map_mcp_server.py：

from fastmcp import FastMCP
import requests

# 创建MCP实例
mcp = FastMCP("MapLookup")

# 定义地图查询工具
@mcp.tool()
def geo_lookup(location: str) -> dict:
    """
    查询地理位置，返回经纬度等信息
    """
    url = "https://nominatim.openstreetmap.org/search"
    params = {
        "q": location,
        "format": "json",
        "limit": 1
    }
    headers = {"User-Agent": "FastMCP-Demo/1.0"}
    response = requests.get(url, params=params, headers=headers)
    data = response.json()
    if not data:
        return {"error": f"未找到位置: {location}"}
    result = data[0]
    return {
        "display_name": result["display_name"],
        "latitude": result["lat"],
        "longitude": result["lon"]
    }

# 启动MCP服务
if __name__ == "__main__":
    mcp.run()

1.4 运行MCP服务

在终端执行：

python map_mcp_server.py

默认会在http://localhost:3000启动MCP服务。你将看到如下启动日志：

✅ Server 'MapLookup' running at http://localhost:3000

1.5 测试运行效果（模拟模型调用）

你可以使用Postman或CURL模拟模型调用MCP工具：

curl -X POST http://localhost:3000/tools/geo_lookup \ 
    -H "Content-Type: application/json" \ 
    -d '{"location": "上海"}'

返回结果示例：

{
  "display_name": "上海市, 中国",
  "latitude": "31.230416",
  "longitude": "121.473701"
}

1.6 集成到大模型（如Claude、ChatGPT）

如果你使用支持MCP的大模型（如Claude 3、OpenAI GPT - 4.5 with MCP），你只需将MCP服务器地址注册为工具服务，模型即可通过自然语言调用它。示例Prompt：“请告诉我北京的经纬度”，模型会自动选择geo_lookup工具并返回准确坐标。

二、企业级MCP服务

2.1 为什么选择FastMCP

• 极速开发体验：仅需3行代码即可创建具备完整功能的MCP服务器。

from fastmcp import FastMCP
mcp = FastMCP("智能客服系统")
@mcp.tool()
def query_order(order_id: str) -> str:
    return f"订单{order_id}状态：已发货"

• 原生Python支持：类型注解自动验证输入参数，支持async/await异步处理，无缝集成Pydantic数据模型，兼容Pillow等主流图像库。

• 企业级协议支持：完整实现Model Context Protocol标准，提供资源(Resources)安全访问控制、工具(Tools)执行审计追踪、上下文(Context)进度管理、图像(Image)自动格式转换。

2.2 五分钟快速入门指南

2.2.1 环境准备

推荐使用uv进行依赖管理：

uv pip install fastmcp

2.2.2 创建首个MCP服务

新建server.py文件：

# 企业知识库服务
from fastmcp import FastMCP

mcp = FastMCP("知识引擎", dependencies=["pymysql"])

@mcp.resource("kb://{doc_id}")
def get_document(doc_id: str) -> str:
    """获取知识库文档内容"""
    return f"文档{doc_id}内容：AI应用最佳实践..."

@mcp.tool()
def search_docs(keyword: str) -> list[str]:
    """全文检索知识库"""
    return [f"相关文档1({keyword})", f"相关文档2({keyword})"]

2.2.3 部署与测试

• 开发模式实时调试：

fastmcp dev server.py --with pymysql

• 生产环境部署：

fastmcp install server.py -e DB_PASSWORD=your_password

2.3 六大核心功能深度解析

2.3.1 资源(Resources)管理

企业数据的安全访问通道：

@mcp.resource("sales://2023/Q4")
def get_sales_report() -> str:
    """生成季度销售分析报告"""
    return "Q4销售额同比增长35%..."

# 动态路径参数支持
@mcp.resource("employee://{id}/profile")
def get_employee(id: int) -> str:
    return f"员工{id}信息：张三｜研发部"

2.3.2 智能工具(Tools)开发

支持复杂业务逻辑的原子操作：

from pydantic import BaseModel

class Order(BaseModel):
    items: list[str]
    address: str

@mcp.tool()
def create_order(order: Order) -> str:
    """创建新订单（支持JSON自动解析）"""
    return f"已创建包含{len(order.items)}件商品的订单"

2.3.3 对话提示(Prompts)模板

标准化LLM交互流程：

@mcp.prompt()
def customer_service(query: str) -> list[dict]:
    return [
        {"role": "system", "content": "你是一名专业客服"},
        {"role": "user", "content": query}
    ]

2.3.4 图像处理(Images)

多媒体数据无缝集成：

from fastmcp import Image
from PIL import Image as PILImage

@mcp.tool()
def generate_watermark(image_path: str) -> Image:
    """添加企业水印"""
    img = PILImage.open(image_path)
    # 添加水印逻辑...
    return Image(data=img.tobytes(), format="png")

2.3.5 上下文(Context)管理

执行过程全生命周期控制：

async def process_data(ctx: Context):
    await ctx.report_progress(0, 100)
    data = await ctx.read_resource("data://raw")
    # 处理逻辑...
    ctx.info("数据处理完成")

2.3.6 多环境部署策略

模式	命令示例	适用场景
开发调试	fastmcp dev server.py	实时热更新、交互测试
Claude集成	fastmcp install server.py	生产环境部署
独立运行	uv run python server.py	自定义容器化部署

2.4 企业级应用案例：智能财务助手

@mcp.resource("finance://reports/{year}")
def get_financial_report(year: int) -> str:
    """获取年度财务报告"""
    return f"{year}年财报：营收10亿元..."

三、谷歌图片搜索MCP Server

3.1 项目背景

在实际业务中，有时需要让AI搜索图片，例如自媒体写公众号、AI写文章批量发布等场景。本案例将指导你如何利用Fastapi - MCP快速搭建一个MCP服务器，以实现谷歌图片搜索功能。

3.2 实现步骤

3.2.1 先跑通代码

1. 在谷歌创建项目project：有两种方式，方式1到谷歌云的后台创建，打开网站https://console.cloud.google.com/apis/credentials点「Create project」；方式2（推荐）直接新建一个Gemini的api key，会自动创建Project，网站https://aistudio.google.com/apikey。

2. 获取谷歌搜索的api key：打开网站https://developers.google.com/custom-search/v1/overview?hl=zh - cn#api_key，点获取密钥，选择第一步中创建好的项目。

3. 获取谷歌搜索引擎的id，也是cx：网站https://programmablesearchengine.google.com/controlpanel/create，填写相关信息后点「创建」，就能看到cx的值。 然后让DeepSeek帮你写谷歌图片搜索的代码。

3.2.2 把这个代码封装成Fastapi接口

1. 安装Fastapi：

pip install uvicorn, fastapi

1. 让Deepseek帮你把之前的代码改成Fastapi代码。

2. 运行python main.py，在浏览器打开端口后添加/docs的地址，就是接口的文档，见到正常的Fastapi部署页面就表示部署成功。

3.2.3 用Fastapi - MCP改造服务端

安装Fastapi - MCP，在上述fastapi代码的基础上添加相关代码。运行后可以通过http://你服务器地址:9797/mcp来访问MCP，注意如果是在本地跑，服务器地址就是localhost。

3.2.4 在AI软件中使用MCP

在Cursor可以直接用url，配置MCP Server，确保「Tools」里有对应的工具。

3.2.5 直接在对话中使用

在AI对话中输入搜索图片的提示词，例如“搜索马斯克的照片”，AI就能正确调用我们的工具。

四、总结

通过以上几个实战案例，我们可以看到FastMCP在不同场景下的强大应用能力。它可以帮助开发者快速构建MCP服务器和客户端，使得大语言模型能够更好地与外部系统进行交互，获取实时信息，执行特定任务。在实际开发中，你可以根据具体需求选择合适的案例进行参考和扩展。