安装与配置 FastMCP

前提条件

安装 FastMCP 之前，请确保您已具备：

Python 3.10+：FastMCP 需要 Python 3.10 或更高版本。
包管理器：我们推荐使用 uv 以获得最佳体验，当然 pip 也能正常工作。

安装方法

使用 uv（推荐）

安装 FastMCP 最快、最可靠的方式：

uv pip install fastmcp

使用 pip

如果您更喜欢 pip：

pip install fastmcp

开发模式安装

若用于开发或获取最新功能：

# 克隆仓库
git clone https://github.com/jlowin/fastmcp.git
cd fastmcp

# 使用 uv 创建并同步环境
uv sync

# 或者在虚拟环境中使用 pip
python -m venv venv
source venv/bin/activate  # 在 Windows 上使用：venv\Scripts\activate
pip install -e .

验证安装

通过创建简单服务器来测试安装：

# test_install.py
from fastmcp import FastMCP

mcp = FastMCP("测试服务器")

@mcp.tool
def hello() -> str:
    """打个招呼。"""
    return "FastMCP，你好！"

if __name__ == "__main__":
    print("FastMCP 安装成功！")
    print(f"服务器名称: {mcp.name}")
    # 解除注释以运行服务器
    # mcp.run()

运行测试：

python test_install.py

您应该会看到：

FastMCP 安装成功！
服务器名称: 测试服务器

项目结构

对于典型的 FastMCP 项目，我们推荐以下结构：

my-mcp-project/
├── server.py          # 主服务器文件
├── tools/             # 工具实现
│   ├── __init__.py
│   ├── math_tools.py
│   └── data_tools.py
├── resources/         # 资源实现
│   ├── __init__.py
│   └── config.py
├── tests/            # 测试文件
│   └── test_server.py
├── requirements.txt   # 依赖项
└── README.md         # 项目文档

环境变量配置

FastMCP 支持通过环境变量进行配置：

# .env 文件
FASTMCP_LOG_LEVEL=DEBUG
FASTMCP_MASK_ERROR_DETAILS=False
FASTMCP_RESOURCE_PREFIX_FORMAT=path

常用环境变量：

FASTMCP_LOG_LEVEL：设置日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
FASTMCP_MASK_ERROR_DETAILS：向客户端隐藏详细错误信息
FASTMCP_RESOURCE_PREFIX_FORMAT：资源前缀的格式（"path" 或 "protocol"）

您的第一个 FastMCP 服务器

我们来创建一个完整的示例服务器：

# server.py
import random
from datetime import datetime
from fastmcp import FastMCP

# 基于配置创建服务器
mcp = FastMCP(
    name="我的第一个 MCP 服务器",
    instructions="""
    此服务器提供包括以下在内的基本实用工具：
    - 数学运算
    - 随机数生成
    - 当前时间信息
    """
)

@mcp.tool
def add_numbers(a: float, b: float) -> float:
    """将两个数字相加。"""
    return a + b

@mcp.tool
def roll_dice(sides: int = 6, count: int = 1) -> list[int]:
    """投掷指定面数的骰子。"""
    if count > 10:
        raise ValueError("最多允许投掷 10 个骰子")
    return [random.randint(1, sides) for _ in range(count)]

@mcp.resource("time://current")
def get_current_time() -> str:
    """获取当前日期和时间。"""
    return datetime.now().isoformat()

@mcp.resource("config://server")
def get_server_config() -> dict:
    """获取服务器配置信息。"""
    return {
        "name": mcp.name,
        "version": "1.0.0",
        "features": ["工具", "资源"],
        "uptime": "刚刚启动"
    }

if __name__ == "__main__":
    print(f"正在启动 {mcp.name}...")
    mcp.run()

运行您的服务器

STDIO 模式（默认）

非常适合本地开发和命令行工具：

python server.py

HTTP 模式

更适合基于 Web 的客户端和开发测试：

# 在您的 server.py 文件中
if __name__ == "__main__":
    mcp.run(transport="http", host="127.0.0.1", port=8000)

然后运行：

python server.py

您的服务器将通过 http://127.0.0.1:8000/mcp/ 访问。

测试您的安装

创建一个简单的测试客户端来验证一切是否正常工作：

# test_client.py
import asyncio
from fastmcp import Client

async def test_server():
    # 通过 HTTP 测试（如果以 HTTP 模式运行）
    async with Client("http://localhost:8000/mcp/") as client:
        # 列出可用工具
        tools = await client.list_tools()
        print("可用工具:", [tool.name for tool in tools])

        # 调用工具
        result = await client.call_tool("add_numbers", {"a": 5, "b": 3})
        print("5 + 3 =", result.text)

        # 读取资源
        time_resource = await client.read_resource("time://current")
        print("当前时间:", time_resource.content)

if __name__ == "__main__":
    asyncio.run(test_server())

常见安装问题

ImportError: 没有名为 'fastmcp' 的模块

确保 FastMCP 安装在正确的 Python 环境中：

# 检查您正在使用的 Python
which python
python --version

# 在正确的环境中安装
python -m pip install fastmcp

版本冲突

如果从 FastMCP 1.0 或官方 MCP SDK 升级：

# 优先卸载旧版本
pip uninstall mcp fastmcp

# 安装最新版本
pip install fastmcp

权限错误

在某些系统上，您可能需要：

# 使用 --user 标志
pip install --user fastmcp

# 或者使用 uv，它能更好地处理此问题
uv pip install fastmcp

后续步骤

现在 FastMCP 已安装并运行，您可以：

构建工具：学习如何创建强大的 MCP 工具
添加资源：向您的 LLM 客户端公开数据源
连接到 Claude Code：集成开发环境
部署到生产环境：为实际应用扩展您的服务器

下一节，我们将深入探讨如何创建能处理复杂操作和数据处理的精密工具。

FastMCP：构建MCP服务器与客户端的完整指南

安装和设置 FastMCP