FastMCP 与 fastmcp-slim：用 Pythonic 方式构建 MCP 服务器与客户端

FastMCP 与 fastmcp-slim用 Pythonic 方式构建 MCP 服务器与客户端【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp本篇技术指南以仓库中 fastmcp_slim/README.md 为骨架系统讲解 FastMCP 的核心设计理念Servers / Apps / Clients 三大能力支柱、快速上手方式以及fastmcp-slim这个依赖精简发行版的安装选型、按需加载机制与运行时配置。读完本文你将掌握从零声明一个 MCP 工具、选择合适安装方式、验证环境并理解精简包边界的方法并能在仓库中通过源码与测试进一步印证每个结论。FastMCP 是什么连接 LLM 与工具数据的协议层框架Model Context ProtocolMCP 将 LLM 与外部工具和数据连接起来而 FastMCP 的目标是让开发者从原型到生产一气呵成声明一个 Python 函数schema、输入校验和文档自动生成提供一个 URL传输协商、认证和协议生命周期自动管理。正如 README 所述best practices are built in最佳实践内置——你只需关注业务逻辑MCP 部分开箱即用。FastMCP 围绕三个支柱组织其能力支柱定位说明Servers暴露能力把 Python 函数包装为符合 MCP 协议的 tools、resources 和 promptsApps交互界面让工具在对话流中直接渲染可交互 UIClients连接对方连接任意 MCP 服务器——本地或远程、编程式或 CLI这三条主线在文档站中分别对应 servers/server.mdx、apps/overview.mdx 与 clients/client.mdx也是后续阅读源码时的三大入口目录fastmcp_slim/fastmcp/server/、fastmcp_slim/fastmcp/apps/与fastmcp_slim/fastmcp/client/。快速上手把 Python 函数变成 MCP 工具README 给出了 FastMCP 最小可用示例这也是理解整个框架心智模型的最佳起点from fastmcp import FastMCP mcp FastMCP(Demo ) mcp.tool def add(a: int, b: int) - int: Add two numbers return a b if __name__ __main__: mcp.run()这段代码做了三件事创建服务器实例FastMCP(Demo )传入服务器名称随后所有的装饰器注册都挂载在该实例上声明工具mcp.tool把普通函数add注册为 MCP tool函数的类型注解a: int会被转换为工具输入 JSON Schemadocstring 会成为工具描述返回值类型决定输出 schema启动服务mcp.run()按默认传输方式stdio启动服务器等待客户端连接。仓库中的 examples/simple_echo.py 是最简变体仅一个echo工具而 examples/echo.py 则演示了同一服务器上同时注册工具、静态资源、模板资源与提示词四种组件的完整形态mcp.tool def echo_tool(text: str) - str: Echo the input text return text mcp.resource(echo://static) def echo_resource() - str: return Echo! mcp.resource(echo://{text}) def echo_template(text: str) - str: Echo the input text return fEcho: {text} mcp.prompt(echo) def echo_prompt(text: str) - str: return text从源码结构看mcp.tool装饰器在 fastmcp_slim/fastmcp/server/providers/local_provider/decorators/tools.py 附近实现注册后的工具会经过输入校验见 fastmcp_slim/fastmcp/tools/与 JSON Schema 生成见 fastmcp_slim/fastmcp/utilities/json_schema.py这正是schema、校验、文档自动生成的来源。理解 fastmcp-slim依赖精简的发行版fastmcp_slim/pyproject.toml将其自身描述为 The dependency-slim FastMCP package依赖精简版 FastMCP 包。它的存在与安装体系直接相关完整的fastmcp包是用户面向的发行版而fastmcp-slim是承载可导入代码的依赖精简发行版。核心依赖极小的安装底线fastmcp-slim的硬性依赖只有七个依赖版本约束用途mcp-types2.0.0,3.0.0MCP 协议类型定义只依赖 pydantic 与 typing-extensionsplatformdirs4.0.0跨平台用户数据目录定位用于home设置pydantic[email]2.12.0配置模型与数据校验pydantic-settings2.0.0基于环境变量的设置加载python-dotenv1.1.0.env文件加载rich13.9.4终端美化与 CLI 输出typing-extensions4.0.0Python 版本兼容注意完整mcpSDK 并不在核心依赖里而是被放进了[mcp]extra——这意味着裸装fastmcp-slim也能import fastmcp与读取设置但使用FastMCP/Client时才需要额外能力。Extras 体系按能力按需安装pyproject.toml中定义了一整套 optional dependencies这是整个安装选型的关键。核心 extras 如下Extra主要依赖提供能力mcpmcp2.0.0,3.0.0、httpx2、starlette1.0.1、opentelemetry-api完整 MCP 协议层client/server 共用底座serverfastmcp-slim[mcp]cyclopts、uvicorn、authlib、joserfc、websockets、watchfiles等服务器能力与 CLIclientfastmcp-slim[mcp]authlib、py-key-value-aio客户端能力appsprefab-ui0.18.0对话内交互 UIanthropic/openai/gemini/azure对应厂商 SDK采样sampling等集成能力code-modepydantic-monty实验性代码模式变换从注释看serverextra 还显式声明了FastMCP 全面使用 httpx2与starlette 下限钉在 CVE-2026-48710 修复版本之上的安全考量这些约束都写在了 fastmcp_slim/pyproject.toml 中。惰性导入与安装提示按需加载的包设计fastmcp-slim的顶层 fastmcp_slim/fastmcp/init.py 采用惰性导入 友好错误提示的设计源码注释明确指出这是为了性能优化见#3292Client、Context、FastMCP、FastMCPApp等符号均通过模块级__getattr__按需导入server-only 用户不会为客户端导入链付出成本当对应 extra 未安装时抛出带安装指引的ImportError提示来自 fastmcp_slim/fastmcp/_install_hints.py例如FastMCP server support is not installed. Install fastmcp or fastmcp-slim[server].边界测试 tests/client/test_slim_package_boundaries.py 精确验证了这一设计在屏蔽完整mcp包的条件下import fastmcp、import fastmcp.settings、import fastmcp.types必须成功而fastmcp.FastMCP与fastmcp.Client必须抛出带安装提示的ImportError。该文件还验证了多服务器 MCPConfig 传输当前需要完整 fastmcp 包这一限制。安装与验证推荐方式uvREADME 与 docs/getting-started/installation.mdx 均推荐使用 uv 安装uv pip install fastmcp或作为项目依赖添加uv add fastmcppip 安装与按需 extraspip install fastmcp按能力拆分安装fastmcp-slimpip install fastmcp-slim[server] # 仅服务器能力 CLI pip install fastmcp-slim[client] # 仅客户端能力 pip install fastmcp-slim[server,apps] # 服务器 对话内交互 UI这里存在一个等价关系fastmcp完整包 ≈fastmcp-slim的 server/client 能力之和因此_install_hints.py中的提示总是同时给出两种安装路径。验证安装安装完成后运行fastmcp version该命令由 fastmcp_slim/fastmcp/cli/cli.py 中的version命令实现输出包括 FastMCP 版本、MCP 版本、Python 版本、平台与 FastMCP 根路径并支持--copy参数把信息复制到剪贴板。CLI 还自带更新检查默认仅检查稳定版可通过FASTMCP_CHECK_FOR_UPDATES调整。故障排查pip 升级后的 import 失败官方安装指南记录了一个与fastmcp-slim迁移直接相关的已知问题从 FastMCP 3.2 及更早版本用 pip 升级到 3.3 及之后版本时可能出现import fastmcp抛ModuleNotFoundError。原因正是 FastMCP 3.3 起可导入代码迁入了fastmcp-slim发行版单条 pip 升级命令可能先装新文件、又在卸载旧fastmcp发行版时删掉这些路径。修复方式是强制重装pip install --force-reinstall fastmcp若仍未解决则彻底清理后重装pip uninstall -y fastmcp fastmcp-slim pip install fastmcpuv由于先卸载再安装的顺序不受此问题影响。运行时配置FASTMCP_ 环境变量与 Settingsfastmcp-slim内置的 fastmcp_slim/fastmcp/settings.py 基于pydantic-settings定义全局配置所有设置项均以FASTMCP_为前缀通过环境变量或.env文件注入默认.env可用FASTMCP_ENV_FILE覆盖。几个关键项设置环境变量示例默认值说明log_levelFASTMCP_LOG_LEVELDEBUGINFO日志级别log_enabledFASTMCP_LOG_ENABLEDfalsetrue是否启用日志transportFASTMCP_TRANSPORThttpstdio默认传输方式stdio/http/sse/streamable-httphost/portFASTMCP_PORT8080127.0.0.1/8000HTTP 监听地址strict_input_validationFASTMCP_STRICT_INPUT_VALIDATIONtruefalse工具输入是否严格校验默认宽松强转mask_error_detailsFASTMCP_MASK_ERROR_DETAILStruefalse是否隐藏用户函数抛出的错误细节mcp_camelcase_compatFASTMCP_MCP_CAMELCASE_COMPATfalsetrueMCP SDK v2 snake_case 重命名后的 camelCase 兼容垫片开关telemetry_modeFASTMCP_TELEMETRY_MODEoffnativeOpenTelemetry 原生埋点模式show_server_bannerFASTMCP_SHOW_SERVER_BANNERfalsetrue启动时是否显示服务器横幅其中mcp_camelcase_compat对应的兼容垫片由 fastmcp_slim/fastmcp/_compat.py 在包导入时无条件安装但每个垫片的读取都实时检查该设置因此可在运行时开关见__init__.py注释。Settings还提供get_setting/set_setting方法支持__分隔的嵌套设置读写。升级与版本策略README 与官方安装指南共同覆盖了四类升级路径从 FastMCP 3 升级多数服务器无需改动即可运行在新版本上具体破坏性变更见 docs/getting-started/upgrading/from-fastmcp-3.mdx从 FastMCP 2 升级见 docs/getting-started/upgrading/from-fastmcp-2.mdx从 MCP SDK v1/v2 的高层 APIFastMCP迁移v1 通常只需改一行 importv2 的MCPServer迁移以重命名为主从低层Server类迁移根据 handler 注册方式区分装饰器形式对应 SDK v1构造参数形式对应 SDK v2。版本策略上项目遵循语义化版本并针对快速演进的 MCP 生态做务实调整破坏性变更可能出现在 minor 版本因此官方建议生产环境钉死精确版本例如fastmcp4.0.0而非fastmcp4.0.0。在仓库中继续深入如果你想验证本文的每个结论可以在仓库中按以下路径继续安装与 extras 定义fastmcp_slim/pyproject.toml顶层惰性导入与符号暴露fastmcp_slim/fastmcp/init.py安装提示文案fastmcp_slim/fastmcp/_install_hints.py运行时设置与全部FASTMCP_*变量fastmcp_slim/fastmcp/settings.pyCLI 入口fastmcp run/fastmcp version/fastmcp inspect/fastmcp devfastmcp_slim/fastmcp/cli/cli.py精简包边界测试tests/client/test_slim_package_boundaries.py最小服务器示例examples/simple_echo.py 与 examples/echo.py安装与升级指南docs/getting-started/installation.mdx理解fastmcp与fastmcp-slim的二元结构是正确选型安装方式、排查升级问题、以及评估依赖体积的前提。无论你选择完整包的一站式体验还是按 server/client 拆分的最小化安装其核心编程模型始终如一声明一个 Python 函数剩下的交给 FastMCP。【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考