基于FastMCP构建你的第一个MCP服务器：从协议原理到Claude集成实战

1. 项目概述：为什么选择 FastMCP 作为你的第一个 MCP 服务器？

如果你对 AI 应用开发感兴趣，尤其是想让大语言模型（比如 ChatGPT、Claude 等）能够调用你自定义的工具或数据，那么你肯定绕不开“模型上下文协议”（Model Context Protocol，简称 MCP）。简单来说，MCP 就像一套标准化的“插座”和“插头”规范，让不同的 AI 模型（插头）可以安全、便捷地接入各种工具和数据源（插座）。而构建一个 MCP 服务器，就是亲手打造一个这样的“插座”。

那么，为什么是 FastMCP？在众多实现 MCP 协议的框架中，FastMCP 以其“快”和“简单”脱颖而出。它基于 Python 的异步框架 FastAPI 构建，这意味着你不仅能享受到 MCP 协议带来的标准化好处，还能利用 FastAPI 的现代、高性能特性，以及极其直观的声明式 API 编写方式。对于新手而言，FastMCP 极大地降低了入门门槛——你不需要从零开始理解 MCP 协议底层的 JSON-RPC 通信细节，只需要像写普通 Python 函数一样，用装饰器声明你的工具，剩下的框架帮你搞定。这就像你要组装一台电脑，FastMCP 直接给了你一套已经焊好主板、接好电源的准系统，你只需要把 CPU、内存（也就是你的业务逻辑）插上去就行。

这个项目，就是带你从零开始，用 FastMCP 搭建你的第一个 MCP 服务器。我们将构建一个具备实用功能的服务器，而不仅仅是一个“Hello World”示例。通过这个过程，你将掌握 MCP 的核心概念、FastMCP 的基本用法，并最终拥有一个可以实际运行、并能被 Claude Desktop 或兼容 MCP 的客户端调用的服务。无论你是想为团队内部集成一个私有数据查询工具，还是想探索 AI 智能体的边界，这都是一个绝佳的起点。

2. 核心概念与工具选型解析

2.1 深入理解 MCP 协议：不只是 API 调用

在动手之前，有必要厘清 MCP 究竟解决了什么问题。传统的 AI 应用扩展方式，比如 OpenAI 的 Function Calling 或 Assistants API，需要开发者将工具的描述和调用逻辑“喂”给模型，并在每次对话中管理状态。这种方式在复杂场景下会变得笨重，且工具逻辑与客户端深度耦合。

MCP 采用了一种更优雅的架构：服务器-客户端模型。MCP 服务器是一个独立的进程，它对外暴露两类核心资源：

1. 工具（Tools）：可供模型调用的函数，例如“查询数据库”、“发送邮件”、“生成图表”。
2. 上下文（Resources）：可供模型读取的静态或动态数据，例如“项目文档”、“实时天气数据API”、“知识库片段”。

MCP 客户端（如 Claude Desktop、集成 MCP 的 IDE）在启动时会连接到一个或多个 MCP 服务器，获取其提供的工具和资源列表。当用户与 AI 对话时，AI 模型可以根据需求，通过客户端向服务器发起工具调用或资源读取请求。关键在于，AI 模型本身并不直接包含工具代码，它只知道“有什么工具可用”以及“如何请求使用它们”。这种解耦带来了巨大的灵活性：服务器可以独立开发、部署和更新，客户端和模型无需改动即可获得新能力。

FastMCP 在这个协议之上，提供了一层极简的抽象。它处理了所有协议级别的通信、序列化、错误处理，让你专注于用@mcp.tool()这样的装饰器来定义工具逻辑。

2.2 环境与工具链准备：打造高效开发工作站

工欲善其事，必先利其器。以下是构建 FastMCP 服务器的推荐环境配置，我会解释每个选择的原因。

1. Python 环境 (3.10+)FastMCP 基于现代 Python 异步特性，因此 Python 3.10 或更高版本是必须的。建议使用pyenv（Mac/Linux）或pyenv-win（Windows）来管理多个 Python 版本，为项目创建独立的虚拟环境，避免依赖冲突。

# 创建并进入项目目录 mkdir my-first-mcp-server && cd my-first-mcp-server # 创建虚拟环境（这里使用 Python 3.10） python3.10 -m venv venv # 激活虚拟环境 # Mac/Linux: source venv/bin/activate # Windows: .\venv\Scripts\activate

2. 核心依赖安装我们将安装 FastMCP 及其相关依赖。使用pip从 PyPI 安装是最简单的方式。

pip install fastmcp

这条命令会自动安装fastmcp及其核心依赖，包括fastapi,pydantic,uvicorn等。Uvicorn是一个轻量级、高性能的 ASGI 服务器，是运行 FastAPI（以及 FastMCP）应用的绝佳选择。

3. 开发与调试工具

• 代码编辑器/IDE：VS Code 配合 Python 扩展是极佳选择，它提供出色的语法高亮、调试和代码补全支持。
• API 测试工具：虽然 MCP 协议有特定格式，但初期调试可以使用curl或更友好的图形化工具如Bruno或Hoppscotch。Postman 也可用，但可能需要手动构造 JSON-RPC 请求体。
• 终端：一个功能强大的终端（如 iTerm2, Windows Terminal）对于运行服务器和命令至关重要。

注意：确保你的网络环境能够正常访问 PyPI (pypi.org) 以下载包。如果在依赖安装过程中遇到速度慢或超时问题，可以考虑配置国内的镜像源，例如清华源或阿里云源。这是一个常见的实操坑点，提前解决能节省大量时间。

3. 第一个 MCP 服务器的实战构建

我们将构建一个“智能计算与信息查询”服务器。它包含两个工具：一个进行单位换算，另一个获取指定城市的当前时间（模拟）。这涵盖了工具定义的基本形态。

3.1 项目结构与初始化

在项目根目录 (my-first-mcp-server) 下，创建以下结构：

my-first-mcp-server/ ├── app/ │ ├── __init__.py │ ├── main.py # FastMCP 应用主文件 │ └── tools/ # 工具模块目录 │ ├── __init__.py │ ├── calculator.py │ └── time_query.py ├── requirements.txt └── README.md

这种结构虽然不是强制性的，但遵循了 Python 包的最佳实践，有利于后续功能扩展。在requirements.txt中，目前只需一行：

fastmcp>=1.0.0

3.2 核心工具定义详解

现在，我们来编写具体的工具。首先看app/tools/calculator.py：

# app/tools/calculator.py from fastmcp import mcp from pydantic import BaseModel, Field # 定义输入参数的模型，这确保了类型安全和清晰的文档 class ConversionInput(BaseModel): value: float = Field(..., description="需要转换的数值") from_unit: str = Field(..., description="原始单位，如 'miles', 'kilograms'") to_unit: str = Field(..., description="目标单位，如 'kilometers', 'pounds'") @mcp.tool() async def unit_converter(input: ConversionInput) -> str: """ 在不同单位之间进行转换。 支持长度（英里/公里）、重量（公斤/磅）、温度（摄氏度/华氏度）的转换。 """ # 定义转换率字典 conversion_rates = { ("miles", "kilometers"): 1.60934, ("kilometers", "miles"): 1 / 1.60934, ("kilograms", "pounds"): 2.20462, ("pounds", "kilograms"): 1 / 2.20462, } # 温度转换需要特殊处理 if input.from_unit == "celsius" and input.to_unit == "fahrenheit": result = (input.value * 9/5) + 32 return f"{input.value} {input.from_unit} 等于 {result:.2f} {input.to_unit}" elif input.from_unit == "fahrenheit" and input.to_unit == "celsius": result = (input.value - 32) * 5/9 return f"{input.value} {input.from_unit} 等于 {result:.2f} {input.to_unit}" # 查找标准转换率 key = (input.from_unit, input.to_unit) if key in conversion_rates: rate = conversion_rates[key] result = input.value * rate return f"{input.value} {input.from_unit} 等于 {result:.2f} {input.to_unit}" else: # 如果找不到转换率，返回错误信息。在实际应用中，可以抛出更结构化的异常。 supported_pairs = list(conversion_rates.keys()) + [("celsius", "fahrenheit"), ("fahrenheit", "celsius")] supported_str = ", ".join([f"'{f}' to '{t}'" for f, t in supported_pairs]) return f"错误：不支持从 '{input.from_unit}' 到 '{input.to_unit}' 的转换。当前支持：{supported_str}"

代码解析与实操要点：

1. @mcp.tool()装饰器：这是 FastMCP 的核心魔法。它告诉框架，这个异步函数是一个 MCP 工具，需要暴露给客户端。框架会自动提取函数的名称、文档字符串和参数模型来生成工具的描述信息。
2. Pydantic 模型 (ConversionInput)：使用 Pydantic 的BaseModel来定义工具输入，是 FastMCP 的推荐做法。它带来了三大好处：
   • 类型验证：确保客户端传入的数据类型正确（如value必须是数字）。
   • 自动生成文档：Field中的description会直接成为工具描述的一部分，帮助 AI 模型理解每个参数的用途。
   • 清晰的接口契约：使得工具的输入结构一目了然。
3. 异步函数 (async def)：FastMCP 基于异步 I/O。即使你的工具目前是纯计算（CPU密集型），也建议定义为async。如果你的工具未来需要执行网络请求（如调用外部 API）或数据库查询，异步将能显著提升服务器的并发性能。
4. 详细的文档字符串 (Docstring)：函数的""" ... """文档字符串至关重要。AI 模型（如 Claude）会阅读这段描述来决定何时以及如何使用这个工具。描述应清晰、简洁，说明工具的功能、适用场景和可能的输出。

接下来，我们创建第二个工具app/tools/time_query.py，模拟查询城市时间：

# app/tools/time_query.py from fastmcp import mcp from pydantic import BaseModel, Field from datetime import datetime import pytz # 需要额外安装：pip install pytz class CityTimeInput(BaseModel): city_name: str = Field(..., description="城市名称，例如 'Shanghai', 'New York', 'London'") @mcp.tool() async def get_city_time(input: CityTimeInput) -> str: """ 获取世界上主要城市的当前日期和时间。 这是一个模拟功能，实际使用时需要接入可靠的时区API。 """ # 一个简单的城市到时区映射（简化版，生产环境应使用更完整的数据库） city_timezone_map = { "shanghai": "Asia/Shanghai", "beijing": "Asia/Shanghai", "new york": "America/New_York", "london": "Europe/London", "tokyo": "Asia/Tokyo", "paris": "Europe/Paris", "sydney": "Australia/Sydney", } city_lower = input.city_name.lower() timezone_str = city_timezone_map.get(city_lower) if not timezone_str: supported_cities = list(city_timezone_map.keys()) return f"错误：暂不支持查询城市 '{input.city_name}' 的时间。当前支持的城市包括：{', '.join(supported_cities)}" try: tz = pytz.timezone(timezone_str) city_time = datetime.now(tz) # 格式化输出 formatted_time = city_time.strftime("%Y-%m-%d %H:%M:%S %Z%z") return f"{input.city_name} 的当前时间是：{formatted_time}" except Exception as e: return f"查询 {input.city_name} 时间时发生错误：{str(e)}"

注意事项：

• 这个工具引入了外部依赖pytz。记得运行pip install pytz来安装它。这引出了一个重要实践：将项目的直接依赖（如fastmcp）和工具的功能性依赖（如pytz,requests,sqlalchemy等）明确区分，并在requirements.txt或pyproject.toml中记录所有依赖。
• 我们使用了模拟数据。在真实项目中，你可能会调用 World Time API 或维护一个更完善的时区数据库。这里模拟的目的是展示工具如何与外部数据/逻辑结合。

3.3 应用主文件集成与启动

现在，我们需要在app/main.py中创建 FastMCP 应用实例，并导入我们定义的工具。

# app/main.py from fastmcp import FastMCP import sys import os # 将当前目录和工具目录加入 Python 路径，确保导入正常（适用于多种启动方式） sys.path.insert(0, os.path.dirname(__file__)) # 创建 FastMCP 应用实例 # 可以在这里配置服务器名称、版本等信息，这些信息会暴露给客户端 app = FastMCP("My First MCP Server", version="0.1.0") # 从工具模块导入工具。导入操作本身就会因为装饰器而完成工具的注册。 try: from tools import calculator, time_query # 你可以选择性地在这里打印日志，确认工具已加载 print(f"工具加载成功: {[calculator.unit_converter, time_query.get_city_time]}") except ImportError as e: print(f"错误：导入工具模块失败 - {e}") sys.exit(1) # 这是启动应用的入口点 if __name__ == "__main__": # 使用 app.run() 启动服务器。默认使用 stdio 传输，这是与 Claude Desktop 等客户端通信的标准方式。 # 你也可以配置其他传输方式，如 SSE (Server-Sent Events) 或 HTTP。 app.run()

关键配置解析：

• FastMCP("My First MCP Server", version="0.1.0")：实例化应用时，可以设置服务器名称和版本。这些元数据有助于客户端识别和管理不同的服务器。
• app.run()：这是启动服务器的核心方法。在默认无参数的情况下，它会使用stdio（标准输入/输出）传输模式。这是 MCP 协议最常见的通信方式之一，尤其适用于与桌面客户端（如 Claude Desktop）集成，客户端会以子进程形式启动服务器并通过管道进行通信。

4. 运行、测试与集成

4.1 启动服务器并进行基础测试

首先，确保你在项目根目录，并且虚拟环境已激活。然后运行主程序：

python -m app.main

如果一切正常，你会看到类似以下的输出，然后程序似乎“挂起”了：

工具加载成功: [<function unit_converter at 0x...>, <function get_city_time at 0x...>] INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete.

这并非挂起，而是服务器正在stdin上等待来自 MCP 客户端的 JSON-RPC 请求。为了测试，我们需要模拟一个客户端请求。我们可以创建一个简单的测试脚本test_request.py：

# test_request.py import json import subprocess import time # 启动服务器进程，并与其 stdin/stdout 建立管道 proc = subprocess.Popen( ['python', '-m', 'app.main'], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True ) # 构造一个 MCP 协议要求的“initialize”请求 init_request = { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "TestClient", "version": "1.0"} } } # 发送初始化请求 proc.stdin.write(json.dumps(init_request) + '\n') proc.stdin.flush() # 读取并打印初始化响应 line = proc.stdout.readline() print("初始化响应:", line) # 构造一个工具调用请求：单位换算 tool_request = { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "unit_converter", "arguments": { "value": 10, "from_unit": "miles", "to_unit": "kilometers" } } } proc.stdin.write(json.dumps(tool_request) + '\n') proc.stdin.flush() line = proc.stdout.readline() print("工具调用响应:", line) # 关闭进程 proc.terminate() time.sleep(0.5) if proc.poll() is None: proc.kill()

运行这个测试脚本：python test_request.py。你应该能看到服务器返回的 JSON 响应，其中包含转换结果"10 miles 等于 16.09 kilometers"。这证明你的 MCP 服务器在协议层面工作正常。

4.2 与 Claude Desktop 集成（实战演练）

这是最令人兴奋的一步：让你构建的工具在 Claude Desktop 中直接可用。

1. 定位 Claude Desktop 配置：

   • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json

2. 编辑配置文件：如果文件不存在，就创建它。添加以下配置，将python路径和你的脚本路径替换为实际值。

{ "mcpServers": { "my-first-server": { "command": "/path/to/your/project/venv/bin/python", "args": [ "/path/to/your/project/my-first-mcp-server/app/main.py" ] } } }

重要提示：

• command必须是虚拟环境中python解释器的绝对路径。你可以通过在项目目录的激活的虚拟环境中运行which python(Mac/Linux) 或where python(Windows) 来获取。
• args中的脚本路径也必须是绝对路径。

3. 重启 Claude Desktop：完全关闭并重新打开 Claude Desktop 应用程序。

4. 验证集成：在 Claude Desktop 中开启一个新对话。如果配置正确，Claude 会在系统提示中加载你的工具。你可以尝试直接提问：“请帮我把 5 公斤换算成磅”或“现在伦敦几点钟了？”。Claude 应该能识别出可用的工具并调用你的服务器来获取答案。

实操心得：与 Claude Desktop 集成时，90% 的问题都出在配置文件路径错误上。务必使用绝对路径，并确保 Claude Desktop 有权限执行该命令。如果工具没有出现，首先检查 Claude Desktop 的日志（通常可以在应用菜单中找到“查看日志”选项），里面会有 MCP 服务器连接失败的详细错误信息，这是排查问题的第一手资料。

5. 进阶功能与最佳实践

5.1 资源（Resources）的暴露与使用

除了工具，MCP 的另一大核心概念是“资源”。资源代表模型可以读取的静态或动态内容，比如文档、配置文件、数据库查询结果片段。在 FastMCP 中，你可以通过装饰器@mcp.resource()来定义一个资源。

假设我们想暴露一个简单的“服务器使用指南”作为可读资源：

# app/resources/guide.py from fastmcp import mcp @mcp.resource(uri="guide://getting-started") async def get_server_guide() -> str: """ 提供本 MCP 服务器的快速入门指南。 """ guide_content = """ # My First MCP Server 使用指南 ## 可用工具 1. **单位转换器 (unit_converter)** - 功能：在常见单位间进行转换。 - 支持：长度(英里/公里)、重量(公斤/磅)、温度(摄氏度/华氏度)。 - 示例：“将10英里转换成公里”。 2. **城市时间查询 (get_city_time)** - 功能：查询主要城市的当前时间。 - 支持城市：上海、北京、纽约、伦敦、东京、巴黎、悉尼等。 - 示例：“现在伦敦是几点？” ## 使用提示 - 直接向我描述你的需求，我会自动选择合适的工具。 - 所有计算和查询均在本地服务器进行，保护隐私。 """ return guide_content

然后在app/main.py中导入这个资源模块即可。客户端初始化时，会获取到这个资源的 URI (guide://getting-started)，模型在需要时可以通过resources/read请求来获取其内容。这对于提供上下文帮助、文档或配置信息非常有用。

5.2 错误处理与日志记录

健壮的生产级服务器必须有良好的错误处理和日志记录。

1. 增强工具内的错误处理：上面的示例已经包含了基本的错误返回。更佳实践是使用 Pydantic 进行更严格的验证，或者在工具内部捕获特定异常，返回结构化的错误信息。

from fastmcp import mcp from pydantic import ValidationError import httpx @mcp.tool() async def query_external_api(input: MyInput): try: async with httpx.AsyncClient() as client: response = await client.get("https://api.example.com/data", params=input.dict()) response.raise_for_status() # 如果状态码不是2xx，抛出HTTPError return response.json() except httpx.HTTPStatusError as e: # 返回对用户/模型友好的错误信息，而非堆栈跟踪 return f"请求外部API失败，状态码：{e.response.status_code}。请稍后重试或检查输入参数。" except Exception as e: # 捕获其他未预料错误 return f"工具执行过程中发生未知错误：{str(e)[:100]}..." # 限制错误信息长度

2. 配置应用级日志：FastMCP 基于 FastAPI，可以使用标准的 Pythonlogging模块。在app/main.py中配置：

import logging logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', handlers=[ logging.FileHandler('mcp_server.log'), # 输出到文件 logging.StreamHandler() # 同时输出到控制台 ] ) logger = logging.getLogger(__name__) # 在工具中可以使用 logger @mcp.tool() async def my_tool(): logger.info("工具 my_tool 被调用") # ... 工具逻辑

5.3 性能优化与安全考量

• 依赖管理：使用requirements.txt或pyproject.toml精确锁定依赖版本，确保环境一致性。考虑使用pip-tools或poetry。
• 异步与同步代码：如果你的工具主要是 CPU 密集型计算（如复杂数学运算），几乎没有 I/O 等待，那么使用async def可能不会带来性能提升，甚至可能因为事件循环调度带来微小开销。但对于涉及网络、文件读写、数据库查询的操作，异步是必须的。对于纯 CPU 任务，你可以使用@mcp.tool(executor="thread")将任务放到线程池中执行，避免阻塞事件循环。
• 输入验证与清理：Pydantic 提供了强大的输入验证。务必充分利用。对于从工具输入中获取并用于构造命令、SQL 查询或文件路径的参数，要进行严格的清理和转义，防止注入攻击。
• 超时控制：对于可能长时间运行的工具，应考虑实现超时机制，避免一个缓慢的工具调用阻塞整个服务器。这可以在工具逻辑内部实现，也可以在某些传输层进行配置。

6. 常见问题与排查技巧实录

在开发和集成过程中，你几乎一定会遇到下面这些问题。这里记录了排查思路和解决方法。

独家避坑技巧：

• 开发阶段使用“回声服务器”测试：在真正实现业务逻辑前，可以先创建一个最简单的工具，比如@mcp.tool()async def echo(text: str): return text。用它来快速验证从 Claude Desktop 到你的服务器的整个通路是否畅通，排除业务逻辑代码的干扰。
• 利用mcp.tool()的name参数：默认情况下，工具在 MCP 中暴露的名称就是函数名。你可以通过@mcp.tool(name="custom_tool_name")来覆盖它。这对于保持后端代码命名规范（如使用蛇形命名my_tool）而前端暴露更友好的名称（如my-tool）很有用。
• 关注传输模式：app.run()默认使用 stdio。如果你打算构建一个通过网络访问的 MCP 服务器（例如用于网页应用），可以研究 FastMCP 对 SSE 或 HTTP 传输模式的支持。这为你打开了更广阔的集成可能性。

构建第一个 MCP 服务器的旅程，从理解协议价值开始，到用 FastMCP 快速实现工具，最后集成到 Claude 这样的智能体中，每一步都充满了实践乐趣。最关键的不是一次成功，而是在遇到配置报错、工具不显示、调用失败时，能够依据日志和系统思维，一步步定位到问题根源。当你第一次在 Claude 的对话窗口中，用自然语言驱动你自己编写的工具完成一个任务时，那种连接虚拟智能与现实能力的成就感，正是开发者持续探索的动力。接下来，你可以尝试接入真实的数据库、调用第三方 API、或者设计更复杂的多步骤协作工具，将你的 MCP 服务器打造成一个功能强大的 AI 能力扩展中心。