1. 项目概述：为什么你需要一个自己的MCP服务器？

如果你最近在折腾AI应用开发，尤其是围绕Claude、GPTs或者其他智能体（Agent）工作流，那你大概率已经听过“MCP”这个词了。MCP，全称是Model Context Protocol，你可以把它理解为一个标准化的“插件协议”。它的核心目标很简单：让AI模型能够安全、标准化地访问外部工具、数据和功能，比如读取你电脑上的文件、查询数据库、调用某个API，或者控制一个智能设备。

那么，为什么我要花30分钟自己动手“Build”一个呢？市面上的MCP工具不是很多吗？这正是关键所在。使用现成的MCP服务器，就像住精装房，虽然方便，但格局、装修都固定了。而自己搭建，意味着你可以定制专属的“瑞士军刀”。想象一下，你可以让AI助手直接查询你公司的内部项目管理系统、分析你私有云盘里的特定格式日志、或者一键触发你本地开发环境的构建脚本。这些高度定制化、与个人或团队工作流深度绑定的能力，是通用工具无法提供的。FastMCP的出现，极大地降低了这个定制门槛。它不是一个庞大的框架，而是一个轻快、直观的“脚手架”，让你能专注于实现业务逻辑本身，而不是陷在协议细节和网络通信的泥潭里。接下来，我就带你从零开始，在30分钟内，打造一个属于你自己的、能实际跑起来的MCP服务器。

2. 核心工具与原理：FastMCP如何让一切变简单？

在深入代码之前，我们有必要花几分钟理解一下FastMCP到底做了什么，以及MCP协议的基本工作模式。这能让你在后续开发中知其然，更知其所以然。

2.1 MCP协议简述：AI的“手”和“眼”

你可以把MCP想象成AI模型（大脑）与外部世界（手、眼、数据库、网络）之间的一个“标准化接口”或“驱动程序”。没有MCP，AI模型就像一个只有思想却不能动弹的人，它知道可以“查天气”，但不知道如何去调用天气API。MCP定义了一套标准的通信方式（基于JSON-RPC），规定了AI模型可以“请求”哪些操作（称为Tools工具），以及可以“读取”哪些信息（称为Resources资源）。

一个典型的MCP工作流是这样的：

1. MCP服务器 ：这是你将要构建的部分。它像一个功能供应商，对外宣告：“我这里提供‘查询数据库’和‘发送邮件’两个工具（Tools），还有一个‘系统状态’信息（Resource）可以读取。”
2. MCP客户端 ：通常是AI应用本身，比如Claude Desktop、Cursor IDE，或者你自己写的AI Agent程序。它负责连接服务器，获取工具和资源列表。
3. 交互过程 ：当用户向AI提出“帮我查一下上个月的销售额”时，AI模型（在客户端内）会判断这个需求需要调用“查询数据库”工具。于是，客户端通过MCP协议向你的服务器发送一个格式化的请求。你的服务器执行真正的数据库查询逻辑，然后将结果格式化，通过协议返回给客户端，最终由AI呈现给用户。

2.2 FastMCP的定位：开发者的“加速器”

原生的MCP协议实现需要处理连接管理、消息序列化、协议版本兼容、错误处理等一系列底层琐事。FastMCP的价值就在于，它把这些底层复杂性全部封装了起来，提供了一套极其简洁的Python装饰器（ @tool , @resource ）和类接口。

它的核心设计哲学是：

• 约定大于配置 ：你几乎不需要写任何样板代码来注册工具或资源。
• 专注业务逻辑 ：你只需要用 @tool 装饰器标记一个Python函数，这个函数就自动变成了一个MCP工具。函数的文档字符串（docstring）会自动成为工具的说明，参数会自动被解析和验证。
• 开箱即用的服务器 ：FastMCP内置了高性能的异步服务器（基于 asyncio 和 uvicorn ），你写好工具后，一行命令就能启动。

举个例子对比： 没有FastMCP，你可能需要手动定义一个工具字典，编写参数验证，处理请求路由。而有了FastMCP，你只需要：

from fastmcp import FastMCP

# 创建服务器实例
mcp = FastMCP("My-Server")

# 使用装饰器声明一个工具
@mcp.tool()
async def get_weather(city: str) -> str:
    """获取指定城市的当前天气。
    
    Args:
        city: 城市名称，例如 'Beijing', 'Shanghai'。
    """
    # 这里是你真正的业务逻辑，比如调用天气API
    return f"The weather in {city} is sunny."

就这么简单。 @mcp.tool() 装饰器帮你完成了MCP工具的所有注册工作，包括名称、描述、参数schema的生成。这种开发体验，是它能实现“30分钟教程”的基石。

注意 ：FastMCP默认使用异步（ async/await ）编程模型。这是因为MCP服务器需要高效处理并发的AI请求。如果你不熟悉异步编程，只需记住在工具函数前加 async ，并在内部调用其他异步库时使用 await 即可。对于纯CPU计算或同步库，可以使用 asyncio.to_thread 进行封装，后续我们会提到。

3. 30分钟实战：从零构建一个智能待办事项管理服务器

理论说得再多，不如动手一试。我们接下来要构建的，是一个“智能待办事项（Todo List）管理服务器”。这个例子非常经典，它涵盖了MCP服务器的几个核心要素：数据管理、工具定义、错误处理。完成后的服务器将提供以下能力：

• 添加待办事项 ：AI助手可以帮你记下新任务。
• 列出所有待办 ：让AI告诉你当前有哪些任务。
• 标记任务完成 ：告知AI哪个任务做完了。
• 清除所有已完成任务 ：一键清理。

我们会使用内存存储来简化，在实际项目中，你可以轻松替换为数据库。

3.1 环境准备与项目初始化

首先，确保你的电脑上安装了Python（建议3.8以上版本）。然后，我们创建一个干净的项目目录并安装依赖。

打开你的终端（命令行），执行以下步骤：

# 1. 创建一个项目目录并进入
mkdir fastmcp-todo-server
cd fastmcp-todo-server

# 2. 创建并激活一个虚拟环境（强烈推荐，避免包冲突）
python -m venv venv
# 在Windows上激活：
# venv\Scripts\activate
# 在macOS/Linux上激活：
# source venv/bin/activate

# 3. 安装核心依赖：fastmcp
pip install fastmcp

fastmcp 这一个包就足够了，它已经包含了运行服务器所需的所有依赖。安装完成后，你的项目目录下应该只有一个 venv 文件夹。接下来，我们创建主程序文件。

# 4. 创建主服务器文件
touch server.py
# 或者直接在编辑器中新建 server.py 文件

现在，用你喜欢的代码编辑器（如VSCode、PyCharm）打开 server.py 文件，我们开始编写代码。

3.2 核心代码逐行解析

我们将分步构建 server.py ，我会详细解释每一部分的作用。

第一步：导入与服务器实例创建

# server.py
import asyncio
from typing import List, Optional
from fastmcp import FastMCP
from pydantic import BaseModel

# 初始化FastMCP服务器，给它起个名字
mcp = FastMCP("Todo-Server")

• asyncio ：Python的异步IO库，我们的工具函数会用到。
• typing ：用于类型注解，让代码更清晰，FastMCP也能利用这些类型信息自动生成更准确的工具参数说明。
• FastMCP ：核心类，我们创建了一个名为 Todo-Server 的服务器实例。这个名字会在客户端连接时显示。
• pydantic.BaseModel ：我们将用它来定义数据结构，Pydantic能提供强大的数据验证和序列化能力。虽然这个简单例子可以不用，但引入它是为了展示更佳实践。

第二步：定义数据模型与“内存数据库”

# 使用Pydantic定义待办事项的数据结构
class TodoItem(BaseModel):
    id: int
    title: str
    description: Optional[str] = None  # 描述是可选的
    is_completed: bool = False          # 默认未完成

# 用一个简单的列表在内存中模拟数据库
# 注意：服务器重启后数据会丢失！生产环境请连接真实数据库。
_todo_db: List[TodoItem] = []
_next_id = 1  # 用于生成简单自增ID

这里我们定义了一个 TodoItem 类，它有ID、标题、描述和完成状态四个字段。使用Pydantic模型的好处是，当我们从AI客户端接收JSON数据时，它可以自动验证数据格式是否正确（例如， id 必须是整数），并转换为Python对象。 _todo_db 列表就是我们的“数据库”， _next_id 用于给每个新任务分配一个唯一ID。

实操心得 ：即使在原型阶段，也建议使用像Pydantic这样的数据验证库。它能提前拦截很多因客户端传递错误格式数据而导致的运行时异常，让服务器的健壮性更强。错误会以清晰的MCP协议错误信息返回给AI，而不是让服务器崩溃。

第三步：实现第一个工具——添加待办事项

@mcp.tool()
async def add_todo_item(title: str, description: Optional[str] = None) -> str:
    """添加一个新的待办事项。
    
    Args:
        title: 待办事项的标题（必填）。
        description: 待办事项的详细描述（可选）。
    """
    global _next_id, _todo_db
    new_item = TodoItem(id=_next_id, title=title, description=description)
    _todo_db.append(new_item)
    _next_id += 1
    return f"待办事项已添加 (ID: {new_item.id}): {title}"

• @mcp.tool() ：这是 魔法发生的地方 。这个装饰器告诉FastMCP，下面的 add_todo_item 函数是一个MCP工具。
• 函数定义：我们定义了一个异步函数。参数 title 和 description 及其类型注解（ str , Optional[str] ）会被FastMCP自动捕获，并生成对应的工具调用规范。 description: Optional[str] = None 表示这个参数是可选的，不传时默认为 None 。
• 文档字符串（ """ ... """ ）： 极其重要！ AI模型（如Claude）主要依靠这个描述来理解工具的用途和参数含义。请务必清晰、准确地填写。 Args: 部分列出了每个参数的说明。
• 函数体：我们创建了一个新的 TodoItem 对象，将其添加到内存列表 _todo_db 中，然后返回一个成功的确认消息。

第四步：实现列出和更新待办事项的工具

@mcp.tool()
async def list_todo_items(show_completed: bool = False) -> str:
    """列出所有待办事项。
    
    Args:
        show_completed: 是否显示已完成的项目，默认为False（只显示未完成）。
    """
    filtered_items = _todo_db if show_completed else [item for item in _todo_db if not item.is_completed]
    
    if not filtered_items:
        return "当前没有待办事项。" if not show_completed else "没有找到任何待办事项（包括已完成）。"
    
    result_lines = []
    for item in filtered_items:
        status = "✅" if item.is_completed else "⏳"
        desc = f" - {item.description}" if item.description else ""
        result_lines.append(f"{status} [{item.id}] {item.title}{desc}")
    
    return "\n".join(result_lines)

@mcp.tool()
async def complete_todo_item(item_id: int) -> str:
    """根据ID标记一个待办事项为已完成。
    
    Args:
        item_id: 要标记为完成的待办事项的ID。
    """
    global _todo_db
    for item in _todo_db:
        if item.id == item_id:
            if item.is_completed:
                return f"事项 [{item_id}] 已经是完成状态。"
            item.is_completed = True
            return f"事项 [{item_id}] 已被标记为完成。"
    return f"错误：未找到ID为 {item_id} 的待办事项。"

@mcp.tool()
async def clear_completed_items() -> str:
    """清除所有已完成的待办事项。"""
    global _todo_db
    completed_count = sum(1 for item in _todo_db if item.is_completed)
    # 过滤掉已完成的项，只保留未完成的
    _todo_db = [item for item in _todo_db if not item.is_completed]
    return f"已清除 {completed_count} 个已完成的事项。"

• list_todo_items : 这个工具演示了如何处理布尔型参数和简单的过滤逻辑。返回格式化的字符串，方便AI阅读。
• complete_todo_item : 演示了如何通过ID查找并更新数据项，并包含了简单的错误处理（未找到ID）。
• clear_completed_items : 一个无参数的工具，展示了如何操作整个数据集。

第五步：启动服务器

# 这是启动服务器的标准写法
if __name__ == "__main__":
    mcp.run()

mcp.run() 会启动FastMCP内置的服务器。默认情况下，它会使用标准输入输出（stdio）进行通信，这是与Claude Desktop等客户端集成的推荐方式。它也会自动寻找可用的网络端口。

3.3 运行与测试你的服务器

代码写完，保存 server.py 。现在让我们先独立测试一下服务器是否正常启动。

在终端中，确保你在项目目录下且虚拟环境已激活，然后运行：

python server.py

你会看到类似这样的输出：

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

这表明你的MCP服务器已经在后台运行，并正在通过stdio等待客户端连接。目前它正在等待，我们暂时按 Ctrl+C 停止它。

如何真正使用它？ 你需要一个MCP客户端。最常用的测试和集成客户端是 Claude Desktop 。你需要配置Claude Desktop来连接你本地开发的这个服务器。

1. 找到Claude Desktop的配置文件位置。
   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows : %APPDATA%\Claude\claude_desktop_config.json
2. 编辑这个JSON文件（如果不存在就创建），添加如下配置：

{
  "mcpServers": {
    "my-todo-server": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["/full/path/to/your/fastmcp-todo-server/server.py"],
      "env": {
        "PYTHONPATH": "/full/path/to/your/fastmcp-todo-server"
      }
    }
  }
}

关键配置解析 ：

• command : 必须指向你虚拟环境中的Python解释器 绝对路径 。这是最常见的错误来源。在终端中执行 which python (macOS/Linux) 或 where python (Windows，在虚拟环境激活状态下) 可以找到它。
• args : 一个列表，第一个元素就是你 server.py 的 绝对路径 。
• env : 可选，但设置 PYTHONPATH 可以确保Python能正确找到你的项目目录，特别是当你有其他自定义模块时。

配置完成后，重启Claude Desktop。如果配置正确，你会在Claude的输入框上方看到一个小插头图标，或者在与Claude对话时，它能提供 add_todo_item 等工具。你可以直接对Claude说：“请用我的待办事项工具，帮我添加一个‘写项目周报’的任务。”

4. 进阶技巧与生产环境考量

一个能在30分钟内跑起来的服务器是伟大的第一步，但要把它用于实际工作流，还需要考虑更多。这部分就是帮你把玩具变成工具的“打磨”过程。

4.1 错误处理与日志记录

上面的示例代码只有最基本的错误反馈。一个健壮的生产级服务器需要更完善的错误处理。

import logging
from fastmcp import FastMCP

# 配置日志，方便调试
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

mcp = FastMCP("Robust-Todo-Server")

@mcp.tool()
async def safe_complete_todo(item_id: int) -> str:
    """安全地标记待办为完成，包含详细错误处理和日志。"""
    try:
        # ... 查找逻辑 ...
        if not found:
            # 记录警告日志
            logger.warning(f"尝试完成不存在的待办事项 ID: {item_id}")
            # 返回对用户/AI友好的错误信息
            return f"错误：未找到ID为 {item_id} 的待办事项。请使用 list_todo_items 工具查看当前列表。"
        # ... 更新逻辑 ...
        logger.info(f"成功完成待办事项 ID: {item_id}")
        return f"事项 [{item_id}] 已完成。"
    except Exception as e:
        # 捕获未预期的异常，避免服务器崩溃
        logger.error(f"完成待办事项时发生未知错误: {e}", exc_info=True)
        # 返回通用错误，避免泄露内部细节
        return "服务器处理请求时发生内部错误，请稍后重试。"

要点 ：

• 使用 try...except ：包裹核心业务逻辑，防止未处理的异常导致整个MCP会话中断。
• 分级日志 ：使用 logging 模块记录 INFO 、 WARNING 、 ERROR 等级别的日志。这在排查线上问题时至关重要。
• 友好的错误消息 ：返回给AI的错误信息应有助于用户（或AI）进行下一步操作，而不是冰冷的“错误”。

4.2 性能优化：异步与同步代码的抉择

FastMCP基于异步IO，这意味着你的工具函数最好是异步的（ async def ），并且在执行I/O操作（网络请求、数据库查询、文件读写）时使用 await 调用异步库。

如果你的操作是CPU密集型或只能调用同步库怎么办？ 长时间阻塞的同步操作会“卡住”整个事件循环，影响服务器响应其他并发请求。正确的做法是使用 asyncio.to_thread 将其放到单独的线程中执行。

import asyncio
import time

@mcp.tool()
async def heavy_calculation(input_data: str) -> str:
    """一个模拟的CPU密集型计算任务。"""
    # 错误的做法：直接调用同步阻塞函数
    # result = sync_cpu_heavy_function(input_data) # 这会阻塞事件循环！
    
    # 正确的做法：放到线程池中运行
    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(
        None, sync_cpu_heavy_function, input_data
    )
    return f"计算结果: {result}"

def sync_cpu_heavy_function(data):
    """这是一个假设的同步CPU密集型函数。"""
    time.sleep(2)  # 模拟耗时计算
    return data.upper()

4.3 连接真实数据源

内存列表只是演示。真实场景需要连接数据库。以连接SQLite为例：

import aiosqlite  # 异步SQLite驱动
from contextlib import asynccontextmanager

DB_PATH = "todos.db"

# 生命周期管理：服务器启动时连接数据库，关闭时断开
@asynccontextmanager
async def lifespan(app):
    # 启动时
    mcp.db_conn = await aiosqlite.connect(DB_PATH)
    await init_db(mcp.db_conn)  # 初始化表
    yield
    # 关闭时
    await mcp.db_conn.close()

# 将生命周期管理器附加到MCP服务器
mcp = FastMCP("Todo-Server", lifespan=lifespan)

async def init_db(conn):
    await conn.execute("""
        CREATE TABLE IF NOT EXISTS todos (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            title TEXT NOT NULL,
            description TEXT,
            is_completed BOOLEAN DEFAULT 0
        )
    """)
    await conn.commit()

@mcp.tool()
async def add_todo_to_db(title: str, description: Optional[str] = None) -> str:
    """添加待办到数据库。"""
    async with mcp.db_conn.cursor() as cursor:
        await cursor.execute(
            "INSERT INTO todos (title, description) VALUES (?, ?)",
            (title, description)
        )
        await mcp.db_conn.commit()
        new_id = cursor.lastrowid
    return f"待办事项已添加 (数据库ID: {new_id}): {title}"

这里的关键是使用异步数据库驱动（如 aiosqlite , asyncpg ），并利用FastMCP的 lifespan 参数来管理数据库连接的生命周期，确保资源正确初始化和清理。

5. 调试、部署与集成指南

开发完成后，你会面临如何调试、如何让它在后台稳定运行，以及如何集成到不同客户端的问题。

5.1 调试技巧：没有客户端的测试

在开发初期，频繁重启Claude Desktop来测试很麻烦。你可以使用FastMCP提供的 独立测试模式 。

创建一个测试脚本 test_server.py ：

import asyncio
import sys
import json
# 假设你的server.py在同一目录，且将mcp实例导出
# 你需要稍微修改server.py，将`mcp`实例定义为模块变量以便导入
# 例如在server.py末尾加上: `app = mcp`
from server import app  # 导入你的FastMCP实例

async def test_tool():
    # 模拟一个MCP调用
    # 注意：这是底层测试，实际更推荐用客户端测试
    print("测试 add_todo_item...")
    # 这里演示的是直接调用函数（绕过协议层），仅用于逻辑验证
    # 真正的协议测试需要模拟stdio通信，较为复杂。
    # 更实用的方法是：临时修改server.py，在mcp.run()前加一段测试代码。
    pass

if __name__ == "__main__":
    # 一个简单的集成测试：直接运行服务器并发送测试命令（需要一些额外工作）
    # 更简单粗暴的调试方法：使用 `print` 语句在工具函数里输出日志。
    print("请直接运行 server.py，并通过配置好的Claude Desktop进行功能测试。")
    print("对于逻辑调试，可以在工具函数内使用 logging 或 print。")

更实用的方法是 结构化日志 。在 server.py 开头配置日志，并在每个工具的关键步骤记录信息，然后通过观察日志输出来调试。

5.2 部署为系统服务（以Linux为例）

要让服务器在后台持续运行，并在开机时自动启动，可以将其配置为系统服务。

创建一个服务文件 /etc/systemd/system/mcp-todo-server.service ：

[Unit]
Description=FastMCP Todo List Server
After=network.target

[Service]
Type=simple
# 关键：指定工作目录和Python解释器路径
WorkingDirectory=/home/yourname/fastmcp-todo-server
ExecStart=/home/yourname/fastmcp-todo-server/venv/bin/python /home/yourname/fastmcp-todo-server/server.py
Restart=always  # 崩溃后自动重启
RestartSec=10
User=yourname
# 环境变量，如果需要
Environment="PYTHONPATH=/home/yourname/fastmcp-todo-server"

[Install]
WantedBy=multi-user.target

然后执行：

sudo systemctl daemon-reload
sudo systemctl enable mcp-todo-server.service
sudo systemctl start mcp-todo-server.service
sudo systemctl status mcp-todo-server.service  # 查看状态

这样，你的MCP服务器就作为一个守护进程在后台稳定运行了。Claude Desktop的配置中， command 可以改为 /usr/bin/nc (netcat) 或使用本地socket来连接这个常驻服务，而不是每次启动Python脚本。不过，更常见的生产模式是让客户端（如Claude Desktop）直接执行你的脚本，因为MCP设计为按需启动。

5.3 集成到其他客户端

除了Claude Desktop，你的MCP服务器可以集成到任何支持MCP协议的客户端。

• Cursor IDE : Cursor也支持MCP。配置方式类似，通常在Cursor的设置（Settings）中寻找MCP或Composer相关配置项，添加服务器命令路径。
• 自定义AI Agent : 如果你在使用LangChain、LlamaIndex或自己编写的AI Agent框架，许多框架已经提供了MCP客户端库。你可以用 mcp Python库（由Anthropic官方维护）来编写客户端，主动连接并调用你自己服务器的工具。
• MCP Inspector : 这是一个官方的调试工具，可以图形化界面查看服务器提供的所有工具和资源，并手动调用测试。通过 npm install -g @modelcontextprotocol/inspector 安装，然后用 mcp-inspector 命令运行，在界面中配置你的服务器路径即可。

5.4 常见问题排查速查表

在开发和集成过程中，你可能会遇到以下问题。这里是一个快速排查指南：

问题现象	可能原因	解决方案
Claude Desktop不显示工具	1. 配置文件路径错误。 2. 配置文件格式错误（JSON语法）。 3. Python路径或脚本路径错误。 4. 服务器脚本启动失败。	1. 检查配置文件路径和名称是否正确。 2. 使用JSON验证器检查配置文件。 3. 在终端手动运行配置中的 command 和 args ，看能否成功启动脚本。 4. 查看Claude Desktop的日志（位置因系统而异）获取错误详情。
工具调用失败，返回“未找到”	工具函数定义有误，或MCP协议通信失败。	1. 确保工具函数被 @mcp.tool() 正确装饰。 2. 检查函数名是否在客户端缓存了旧列表，尝试重启客户端。 3. 在服务器代码中增加日志，看请求是否到达。
工具调用超时或无响应	工具函数内部有同步阻塞操作，或陷入死循环。	1. 确保耗时操作使用异步方式或 asyncio.to_thread 。 2. 为工具函数添加超时机制（客户端或服务器端）。 3. 简化工具逻辑进行测试。
服务器启动立即退出	脚本中存在语法错误，或依赖未安装。	1. 在终端直接运行 python server.py ，查看Python报错信息。 2. 确认虚拟环境已激活，且 fastmcp 等依赖已正确安装。
客户端连接后很快断开	服务器在 mcp.run() 前提前退出，或发生了未捕获的异常。	1. 确保 mcp.run() 是脚本的最后执行步骤（在 if __name__ == "__main__": 块内）。 2. 用 try...except 包裹 mcp.run() ，并记录异常。

构建自己的MCP服务器，本质上是在为你的AI助手打造专属的“外挂技能”。从简单的待办列表到复杂的业务系统集成，FastMCP提供的这条快速通道，让想法到实现的路径变得前所未有的短。我个人的体会是，最难的不是写代码，而是清晰地定义“工具”的边界——一个工具应该只做一件事，并且通过清晰的参数和描述，让AI能准确理解和使用它。当你开始习惯以“AI可调用”的视角来设计函数时，你会发现很多日常工作都可以被自动化、智能化。最后一个小技巧是，多利用 pydantic 来定义复杂的输入输出模型，这能让你的工具在AI眼中显得更“可靠”，从而获得更高的调用成功率。