name: fastmcp-server description: FastMCP 3.0 构建 MCP 服务器的完整指南 - 工具、资源、认证、提供者、中间件和部署。适用于创建 Python MCP 服务器或集成 AI 模型与外部工具和数据。 version: 1.0.0 author: FastMCP 社区 license: MIT tags: [FastMCP, MCP, Python, AI, 工具, 服务器, 认证, 提供者] dependencies: []

FastMCP 3.0 服务器开发

FastMCP 3.0 构建生产就绪 MCP（模型上下文协议）服务器的完整参考 - 这是一个快速、Pythonic 的框架，用于连接 LLM 到工具和数据。

何时使用此技能

使用 FastMCP Server 时：

在 Python 中创建新的 MCP 服务器
向 MCP 服务器添加工具、资源或提示
实现认证（OAuth、OIDC、令牌验证）
设置中间件用于日志记录、速率限制或授权
配置提供者（本地、文件系统、技能、自定义）
构建具有遥测和存储的生产 MCP 服务器
从 FastMCP 2.x 升级到 3.0

关键领域涵盖：

工具与资源（核心）：装饰器、验证、返回类型、模板
上下文与依赖注入（核心）：MCP 上下文、依赖注入、后台任务
认证（安全）：OAuth、OIDC、令牌验证、代理模式
授权（安全）：基于范围和基于角色的访问控制
中间件（高级）：请求/响应管道、内置中间件
提供者（高级）：本地、文件系统、技能和自定义提供者
功能（高级）：分页、采样、存储、OpenTelemetry、版本控制

快速参考

核心模式

创建带有工具的服务器：

from fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

创建资源：

@mcp.resource("data://config")
def get_config() -> dict:
    """Return server configuration"""
    return {"version": "1.0", "debug": False}

创建资源模板：

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: str) -> dict:
    """Get a user's profile by ID"""
    return fetch_user(user_id)

创建提示：

@mcp.prompt
def review_code(code: str, language: str = "python") -> str:
    """Review code for best practices"""
    return f"Review this {language} code:

{code}"

运行服务器：

if __name__ == "__main__":
    mcp.run()

# 或带有传输选项：
# mcp.run(transport="sse", host="0.0.0.0", port=8000)

在工具中使用上下文

from fastmcp import FastMCP, Context

mcp = FastMCP("MyServer")

@mcp.tool
def process_data(uri: str, ctx: Context) -> str:
    """Process data with logging and progress"""
    ctx.info(f"Processing {uri}")
    ctx.report_progress(0, 100)
    data = ctx.read_resource(uri)
    ctx.report_progress(100, 100)
    return f"Processed: {data}"

认证设置

from fastmcp import FastMCP
from fastmcp.server.auth import BearerAuthProvider

auth = BearerAuthProvider(
    jwks_uri="https://your-provider/.well-known/jwks.json",
    audience="your-api",
    issuer="https://your-provider/"
)

mcp = FastMCP("SecureServer", auth=auth)

关键概念

工具

作为 LLM 可执行能力公开的函数。用 @mcp.tool 装饰。支持 Pydantic 验证、异步、自定义返回类型和注解（readOnlyHint、destructiveHint）。

资源与模板

通过 URI 标识的静态或动态数据源。资源使用固定 URI（data://config），模板使用参数化 URI（users://{id}/profile）。支持 MIME 类型、注解和通配符参数。

上下文

Context 对象提供在工具/资源中访问 MCP 功能：日志记录、进度报告、资源访问、LLM 采样、用户征集和会话状态。

依赖注入

使用 Depends() 将值注入工具/资源函数。支持 HTTP 请求、访问令牌、自定义依赖和基于生成器的清理模式。

提供者

控制组件来源。LocalProvider（默认，基于装饰器）、FileSystemProvider（从磁盘上的 Python 文件加载）、SkillsProvider（打包捆绑）或自定义提供者。

认证与授权

多种认证模式：令牌验证（JWT、JWKS）、OAuth 代理、OIDC 代理、远程 OAuth 和完整 OAuth 服务器。授权通过组件上的范围和中间件实现。

中间件

拦截和修改请求/响应。内置中间件用于速率限制、错误处理、日志记录和响应大小限制。自定义中间件通过 @mcp.middleware。

使用参考

详细文档组织在 references/ 文件夹中：

入门指南

getting-started/installation.md - 安装 FastMCP、可选依赖项、验证设置
getting-started/upgrade-guide.md - 从 FastMCP 2.x 迁移到 3.0
getting-started/quickstart.md - 第一个服务器、工具、资源、提示、运行

服务器

server/server-class.md - FastMCP 服务器配置、传输选项、标签过滤
server/tools.md - 工具装饰器、参数、验证、返回类型、注解
server/resources-and-templates.md - 资源、模板、URI、通配符、MIME 类型

上下文

context/mcp-context.md - 上下文对象、日志记录、进度、资源访问、采样
context/background-tasks.md - 带任务支持的长运行操作
context/dependency-injection.md - Depends()、自定义依赖、HTTP 请求、访问令牌
context/user-elicitation.md - 在执行期间请求结构化用户输入

功能

features/icons.md - 工具、资源、提示和服务器的自定义图标
features/lifespans.md - 服务器生命周期管理和启动/关闭钩子
features/client-logging.md - 发送日志消息到 MCP 客户端
features/middleware.md - 请求/响应管道、内置和自定义中间件
features/pagination.md - 分页大型组件列表
features/progress-reporting.md - 报告长运行操作的进度
features/sampling.md - 从客户端请求 LLM 完成
features/storage-backends.md - 内存、文件和 Redis 存储用于缓存和令牌
features/opentelemetry.md - 分布式追踪和可观测性
features/versioning.md - 版本组件和按版本范围过滤

认证

authentication/token-verification.md - JWT、JWKS、内省、静态密钥、自定义
authentication/remote-oauth.md - 将认证委托给上游 OAuth 提供者
authentication/oauth-proxy.md - 带 PKCE、客户端管理的完整 OAuth 代理
authentication/oidc-proxy.md - 带自动发现的 OpenID Connect 代理
authentication/full-oauth-server.md - 完整的内置 OAuth 服务器

授权

authorization.md - 基于范围的访问控制、中间件授权、模式

提供者

providers/local.md - 默认提供者、基于装饰器的组件注册
providers/filesystem.md - 从磁盘上的 Python 文件加载组件
providers/skills.md - 打包和分发组件捆绑
providers/custom.md - 为任何组件源构建自定义提供者

版本历史

v1.0.0（2026年2月）

初始发布覆盖 FastMCP 3.0（发布候选）
7个类别中的30个参考文件
完全覆盖工具、资源、上下文、认证、提供者和功能