✨ FastMCP 实战进阶：构建可远程访问的 MCP 工具服务与客户端（Python 深度解析）
🚀 FastMCP 实战进阶：构建可远程访问的 MCP 工具服务与客户端（Python 深度解析）
从零实现一个基于 FastMCP 的远程 JSON-RPC 工具服务器，支持 HTTP 通信、流式响应、异步客户端调用，适用于 AI 大模型工具链开发。
🌟 引言：MCP 与 FastMCP 的价值
随着大语言模型（LLM）的普及，AI 应用开发不再仅限于模型推理，而是越来越多地需要 为模型提供上下文增强能力，例如：
- 调用外部工具（如数据库、API、本地函数）
- 读取资源（如配置文件、模板、知识库）
- 动态生成上下文（如个性化提示）
这就是 MCP（Model Context Protocol） 的由来。它是一套标准化的 JSON-RPC 协议，使得模型可以远程调用工具和服务。
而 FastMCP 是一个 Python 框架，它极大简化了 MCP 服务端与客户端的开发，开发者只需编写函数，FastMCP 负责处理协议细节。本文将带你完成一个完整、可运行的 FastMCP 项目，包括服务端、客户端、流式输出、异步调用等高级功能。
✅ 实战目标
| 目标 | 描述 |
|---|---|
| ✅ 构建 FastMCP HTTP 服务端 | 支持远程访问，部署灵活 |
| ✅ 注册多个工具函数 | 如 greet, add, multiply |
| ✅ 构建异步客户端 | 支持 call_tool 和 call_tool_stream |
| ✅ 客户端 introspection | 获取服务端工具列表 |
| ✅ 支持流式响应 | 实现流式输出，提高响应效率 |
| ✅ 实现自动类型校验 | 通过类型注解自动推导 Schema |
| ✅ 提供部署建议 | 本地调试 + 公网部署 |
🖥️ 第一步：搭建 FastMCP 服务器
1.1 安装依赖
首先确保你已安装好 fastmcp 模块：
pip install fastmcp
1.2 创建服务器文件 my_server.py
from fastmcp import FastMCP# 创建 FastMCP 实例
# name: 服务名称，建议唯一
# auto_register: 是否自动注册当前模块中的 tool/resource
# debug: 是否启用调试日志
mcp = FastMCP(name="FastMCP-Server", auto_register=True, debug=True)# 工具函数 1：问候
@mcp.tool
def greet(name: str) -> str:"""向用户发送问候"""return f"Hello, {name}!"# 工具函数 2：加法
@mcp.tool
def add(a: int, b: int) -> int:"""两个整数相加"""return a + b# 工具函数 3：乘法
@mcp.tool
def multiply(a: int, b: int) -> int:"""两个整数相乘"""return a * b# 启动服务
if __name__ == "__main__":mcp.run(transport="http", # 使用 HTTP 传输host="127.0.0.1", # 本地地址port=4200, # 自定义端口path="/mcp", # 自定义路径log_level="debug", # 日志等级)
1.3 运行服务器
python my_server.py
服务启动后，默认监听 http://127.0.0.1:4200/mcp，你可以通过浏览器或客户端访问。
🤖 第二步：构建异步客户端
2.1 创建客户端文件 my_client.py
import asyncio
from fastmcp import Clientasync def run_client(name: str):# 创建客户端实例async with Client("http://127.0.0.1:4200/mcp") as client:# 获取工具列表print("🔍 获取所有可用工具：")tools = await client.list_tools()for tool in tools:print(f"工具名称: {tool.name}")print(f"描述: {tool.description}")print(f"参数 Schema: {tool.inputSchema}")print("-" * 50)# 调用工具：greetprint("📞 调用工具 `greet`：")if hasattr(client, "call_tool_stream"):print("使用流式调用：")async for chunk in client.call_tool_stream("greet", {"name": name}):print(chunk, end="")else:print("使用标准调用：")result = await client.call_tool("greet", {"name": name})print(result)# 调用工具：addprint("\n📞 调用工具 `add`：")result = await client.call_tool("add", {"a": 2, "b": 3})print(f"2 + 3 = {result}")# 调用工具：multiplyprint("\n📞 调用工具 `multiply`：")result = await client.call_tool("multiply", {"a": 2, "b": 3})print(f"2 × 3 = {result}")if __name__ == "__main__":asyncio.run(run_client("Ford"))
2.2 运行客户端
python my_client.py
2.3 客户端输出示例
🔍 获取所有可用工具：
工具名称: greet
描述: 向用户发送问候
参数 Schema: {'name': {'type': 'string'}}
--------------------------------------------------
工具名称: add
描述: 两个整数相加
参数 Schema: {'a': {'type': 'integer'}, 'b': {'type': 'integer'}}
--------------------------------------------------
工具名称: multiply
描述: 两个整数相乘
参数 Schema: {'a': {'type': 'integer'}, 'b': {'type': 'integer'}}
--------------------------------------------------
📞 调用工具 `greet`：
使用流式调用：
Hello, Ford!📞 调用工具 `add`：
2 + 3 = 5📞 调用工具 `multiply`：
2 × 3 = 6
🧠 深度解析：FastMCP 的设计亮点
| 功能 | 说明 |
|---|---|
| ✅ 自动 Schema 推导 | FastMCP 通过 typing 注解自动推导函数的输入/输出 Schema，无需手动编写 OpenAPI |
| ✅ 支持流式输出 | 服务端使用 yield，客户端使用 async for 接收流式结果，适合大文本或长处理 |
| ✅ 客户端 introspection | client.list_tools() 获取服务端工具元数据，适合自动化注册、调试、工具发现 |
| ✅ 支持异步工具 | 使用 async def 编写异步工具，FastMCP 会自动识别并包装为异步调用 |
| ✅ 多种传输方式 | 支持 stdio、http、tcp、websocket 多种通信方式，灵活部署 |
| ✅ 可扩展性高 | 可自定义工具、资源、模板、错误处理等，支持扩展到复杂系统 |
🛠️ 可扩展建议与高级用法
✅ 异步工具支持
@mcp.tool
async def async_greet(name: str) -> str:await asyncio.sleep(1)return f"Async Hello, {name}!"
✅ 添加静态资源
@mcp.resource("resource://config")
def get_config() -> dict:return {"version": "1.0", "author": "FastMCP Team"}
✅ 模板资源（动态资源）
@mcp.resource("greetings://{name}")
def get_greeting(name: str) -> str:return f"Hello, {name}! Welcome to the MCP server."
✅ 自定义错误处理
from fastmcp import error@mcp.tool
def divide(a: int, b: int) -> float:if b == 0:raise error.ToolError("除数不能为0")return a / b
🌐 部署建议：从本地到公网
| 场景 | 说明 |
|---|---|
| ✅ 本地调试 | 使用默认 stdio 或 http 模式，无需配置 |
| ✅ 内网部署 | 使用 http 模式，绑定内网 IP |
| ✅ 公网部署 | 使用 uvicorn + Nginx 反向代理，支持 HTTPS |
| ✅ 云服务部署 | 可部署到 Heroku、Vercel、阿里云、腾讯云等 |
✅ 示例：uvicorn 启动
uvicorn my_server:app --reload --host 0.0.0.0 --port 4200
✅ 示例：Nginx 配置
server {listen 80;server_name yourdomain.com;location /mcp {proxy_pass http://127.0.0.1:4200;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;}
}
📌 总结与展望
通过本文你已经掌握如何使用 FastMCP 构建一个支持 HTTP 通信的远程工具服务，并实现客户端的异步调用与流式响应。FastMCP 作为 LLM 上下文增强协议的实现框架，极大简化了开发流程，适合用于构建：
- AI Agent 工具链
- 大模型插件服务
- 智能助手后端
- 企业级 API 服务
🔚 下一步计划
- ✅ 构建 FastMCP 与 LangChain 的集成示例
- ✅ 实现多语言客户端（如 Node.js、Java）
- ✅ 使用 FastMCP 构建企业级 API 网关
- ✅ 对接 Claude、Gemini、Qwen 等大模型的工具链
📣 结语
FastMCP 让你专注于编写高质量的 Python 函数，而不用关心底层的 JSON-RPC 协议与通信细节。希望本教程能帮助你快速上手 FastMCP，并在实际项目中加以应用。欢迎在评论区留言交流你的实战经验！