基于 fastmcp.json 的 FastMCP 服务器声明式配置实战：从 dependencies 参数迁移到单一配置源

基于 fastmcp.json 的 FastMCP 服务器声明式配置实战：从 dependencies 参数迁移到单一配置源

【免费下载链接】fastmcp🚀 The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp

本指南以仓库中的 fastmcp_config_demo 示例 为主线，讲解 FastMCP 官方推荐的服务器配置方式：把入口文件、Python 环境、依赖、传输协议与日志级别全部声明在一个fastmcp.json文件中。读完本文，你将掌握fastmcp.json的三大区块结构（source / environment / deployment）、从旧的dependencies=代码参数迁移的方法、多种启动方式，以及环境变量插值、CLI 参数覆盖、多环境配置等进阶技巧，并能结合源码理解其底层实现原理。

为什么需要 fastmcp.json：从 dependencies 参数说起

在 FastMCP 2.11.4 之前（该写法已标记为 deprecated），服务器的第三方依赖需要在 Python 代码中通过FastMCP(...)构造函数的dependencies参数声明：

mcp = FastMCP("Demo Server", dependencies=["pyautogui", "Pillow"])

这种方式有几个明显的痛点：

• 依赖与代码耦合：换一台机器或换一个场景，需要修改源代码才能调整依赖；
• 导入时机问题：依赖是在服务器代码被导入之后才被察觉的，缺少依赖时会出现 import-time 错误；
• 难以共享：想把自己的服务器配置分享给同事或部署到 CI，必须连同源码一起传递隐性信息。

现在，依赖声明被移到了fastmcp.json配置文件中：

{ "environment": { "dependencies": ["pyautogui", "Pillow"] } }

这种声明式配置成为 FastMCP 项目的推荐方式（官方文档 server-configuration 将其定位为 canonical and preferred way），它用一份结构化、可共享、可校验的文件，取代了记忆命令行参数或编写 shell 脚本的繁琐流程。

认识示例项目：一份完整的 fastmcp.json

仓库中的 examples/fastmcp_config_demo 目录包含三个文件：README.md（使用说明）、fastmcp.json（配置文件）和 server.py（服务器代码）。

配置文件完整内容如下：

{ "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json", "source": { "path": "server.py" }, "environment": { "python": "3.11", "dependencies": ["pyautogui", "Pillow"] }, "deployment": { "transport": "stdio", "log_level": "INFO" } }

与之配套的 server.py 是一个"屏幕截图演示"服务器，代码中不再出现任何依赖声明，只负责定义工具：

from fastmcp import FastMCP from fastmcp.utilities.types import Image # Create server - dependencies are now in fastmcp.json mcp = FastMCP("Screenshot Demo") @mcp.tool def take_screenshot() -> Image: """Take a screenshot of the user's screen and return it as an image.""" import pyautogui ...

注意两个细节：pyautogui和Pillow虽然在工具函数内部import，但它们的安装声明完全由fastmcp.json的environment.dependencies负责，服务器源码保持了纯粹的"业务代码"形态。take_screenshot返回 FastMCP 的Image类型（截图压缩为 JPEG 以控制体积），而第二个工具analyze_colors则演示了同一服务器如何复用pyautogui依赖做屏幕主色分析。

fastmcp.json 的三大区块结构

fastmcp.json围绕三个问题组织配置，每个区块解决一类关切：

从源码 mcp_server_config.py 可以看到，MCPServerConfig模型正是由source、environment、deployment三个 Pydantic 字段构成，environment和deployment都带有默认工厂（UVEnvironment()与Deployment()），因此省略时自动取默认值，只有source是必需的。

source：告诉 FastMCP 服务器代码在哪

source决定 FastMCP 如何找到并加载服务器。当前支持"filesystem"类型（本地 Python 文件，也是默认类型，省略type即视为 filesystem），未来将扩展"git"（版本库）与"cloud"（托管服务器）类型。

关键字段：

• path（必填）：指向包含 FastMCP 服务器的 Python 文件路径，相对路径以配置文件所在目录为基准解析（源码 filesystem.py 中同样按此约定解析）。
• entrypoint（可选）：模块内服务器实例或工厂函数的名称。可以是mcp = FastMCP("MyServer")这样的实例，也可以是无参数、返回 FastMCP 服务器的函数。省略时 FastMCP 会在mcp、server、app等常见名称中自动查找。

示例中的配置"source": { "path": "server.py" }省略了entrypoint，此时 FastMCP 自动探测到server.py中定义的mcp实例（见 server.py）。

environment：声明 Python 环境与依赖

environment控制服务器的构建期环境，确保服务器在精确的 Python 版本与依赖集合下运行。FastMCP 采用可扩展的环境系统（基类Environment），目前内置UVEnvironment（type省略时默认"uv"），由uv负责依赖解析与隔离环境创建。

核心字段（定义于 uv.py）：

• python：Python 版本约束。支持精确版本"3.12"、最低版本">=3.10"、版本区间">=3.10,<3.13"三种写法。
• dependencies：pip 包列表，支持 PEP 508 版本说明符，如["pandas>=2.0", "requests", "httpx"]。
• requirements：requirements.txt文件的路径，相对配置文件位置解析。
• project：包含pyproject.toml的项目目录路径，用于 uv 项目级管理。
• editable：以可编辑（开发）模式安装的包路径列表，支持多个路径，适合 monorepo 或共享库场景，如["."]或[".", "../shared-lib"]。

只要设置了以上任一字段，FastMCP 就会自动用uv创建隔离环境。示例中的"python": "3.11"会把 Python 版本固定为 3.11，"dependencies": ["pyautogui", "Pillow"]则声明两个运行依赖。

deployment：控制服务器的运行方式

deployment控制服务器的运行时行为，包括传输协议、网络绑定、日志级别、环境变量与执行上下文（定义于 mcp_server_config.py 的Deployment模型）：

示例配置使用了"transport": "stdio"与"log_level": "INFO"，即默认的桌面客户端通信方式加标准日志输出。

启动服务器：多种运行方式

有了fastmcp.json，启动服务器变得极其简单。CLI 会自动探测当前目录下名为fastmcp.json的文件（源码 find_config 只精确匹配这个文件名）：

# 方式一：自动探测当前目录下的 fastmcp.json cd examples/fastmcp_config_demo fastmcp run # 方式二：显式指定配置文件 fastmcp run examples/fastmcp_config_demo/fastmcp.json # 方式三：开发模式，附带 Inspector UI fastmcp dev examples/fastmcp_config_demo/fastmcp.json

在 run.py 中可以看到运行流程：load_mcp_server_config()通过MCPServerConfig.from_file()解析 JSON，随后调用config.deployment.apply_runtime_settings(config_path)应用环境变量与工作目录等运行时设置；接着把deployment中的 transport / host / port / path / log_level / args 与 CLI 参数合并（CLI 优先），再通过config.source.load_server()加载服务器并运行。

注意：fastmcp.json按严格 JSON 解析，不支持注释和尾随逗号。此外，只有文件名精确为fastmcp.json才会被自动探测；其他命名（如dev.fastmcp.json、prod.fastmcp.json）必须显式传入路径。

从命令行参数迁移：对照与等价关系

如果你现在还在用一长串命令行参数或uv run --with ...脚本，迁移到fastmcp.json后整个工作流会被大幅简化。以下是一组典型等价对照：

迁移前的 CLI 命令：

uv run --with pandas --with requests \ fastmcp run server.py \ --transport http \ --port 8000 \ --log-level INFO

迁移后的 fastmcp.json：

{ "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json", "source": { "path": "server.py", "entrypoint": "mcp" }, "environment": { "dependencies": ["pandas", "requests"] }, "deployment": { "transport": "http", "port": 8000, "log_level": "INFO" } }

之后只需要一条命令：fastmcp run。

CLI 参数覆盖：临时调整不必改文件

CLI 参数的优先级高于配置文件值，方便做临时调整（详见官方文档 CLI Override Behavior 一节）：

# 配置里写的是 8000 端口，这里临时覆盖为 8080 fastmcp run fastmcp.json --port 8080 # 配置里是 stdio，临时切换为 HTTP fastmcp run fastmcp.json --transport http # 追加配置里没有的依赖 fastmcp run fastmcp.json --with requests --with httpx

跳过环境准备：--skip-env / --skip-source

当目标环境已经就绪（例如已在激活的虚拟环境中、依赖已预装的 Docker 容器、CI 已预构建环境、或正处于 uv 管理的环境内），可以用--skip-env跳过环境创建，避免无限递归：

fastmcp run fastmcp.json --skip-env

对于未来支持的需要"拉取源码"的 source 类型（git / cloud），若源码已在本地，可搭配--skip-source。对本地 filesystem 源而言该参数无实际影响。

预构建环境：fastmcp project prepare

在部署场景中，可以把"建环境"（慢）与"跑服务"（快）分离。fastmcp project prepare会创建一个持久化的 uv 项目并把依赖全部预装好：

# 创建持久化环境 fastmcp project prepare fastmcp.json --output-dir ./env # 复用预构建环境运行服务器 fastmcp run fastmcp.json --project ./env

环境变量插值：动态配置的秘密武器

deployment.env字段支持${VAR_NAME}语法做运行时插值。底层实现位于 apply_runtime_settings：正则\$\{([^}]+)\}匹配占位符，若系统环境变量存在则替换，否则保留占位符原样（不会抛错，也不会替换为空字符串）。

{ "deployment": { "env": { "API_URL": "https://api.${ENVIRONMENT}.example.com", "DATABASE_URL": "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}/mydb", "CACHE_KEY": "myapp_${ENVIRONMENT}_${VERSION}" } } }

假设系统已设置ENVIRONMENT=production、DB_HOST=db.example.com，运行时就得到https://api.production.example.com、postgres://${DB_USER}:...等解析结果。这特别适用于：开发 / 预发布 / 生产多环境共用同一份配置、敏感值不入库、动态拼接 URL 与连接串、按环境生成前缀或后缀等场景。cwd字段同样支持相对路径按配置文件位置解析后os.chdir。

多环境配置与共享

一个常用模式是维护多份命名配置，分别面向不同环境：

• fastmcp.json—— 默认配置（唯一会被自动探测的文件名）
• dev.fastmcp.json—— 开发环境（HTTP + DEBUG 日志）
• prod.fastmcp.json—— 生产环境（0.0.0.0绑定 + 严格日志 + requirements 文件）

fastmcp run dev.fastmcp.json # 开发 fastmcp run prod.fastmcp.json # 生产

配合 IDE 校验体验更好。在文件顶部声明$schema后（地址为仓库 schema 目录 docs/assets/schemas 下生成的版本化 schema，亦可通过 generate_schema 在本地重新生成），VS Code 等现代 IDE 会自动提供自动补全、校验与内联文档。

底层原理：一次 fastmcp run 的完整旅程

结合源码梳理一次fastmcp run fastmcp.json的执行链路：

1. 解析配置：MCPServerConfig.from_file()读取 JSON 并通过 Pydantic 校验，source/environment/deployment各自经 field_validator 归一化为类型化对象（见 mcp_server_config.py）。
2. 应用运行时设置：deployment.apply_runtime_settings()先完成env插值并写入os.environ，再按需chdir到cwd。
3. 准备环境：若environment中配置了 python / dependencies / requirements / project / editable 任一字段，则调用UVEnvironment.prepare()——uv init初始化项目、uv python pin固定版本、uv add --no-sync添加依赖（注意源码 uv.py 会自动把fastmcp追加进依赖列表）、最后uv sync安装。若系统未安装 uv，会抛出明确错误提示安装命令。
4. 合并 CLI 覆盖：transport / host / port / path / log_level / args 以"CLI 优先"原则合并（见 run.py）。
5. 加载并运行服务器：source.load_server()按 entrypoint 探测规则加载服务器实例，最终调用server.run_async(**kwargs)。

整个过程保证了依赖一定在服务器被导入前就绪，这也是"无导入期错误"这一收益的根源。

收益总结

采用fastmcp.json声明式配置带来的核心收益（原文档与官方文档的共同结论）：

• 单一事实来源：入口、环境、依赖、运行时全部集中在一处；
• 环境隔离：依赖安装于 uv 管理的隔离环境，不污染系统 Python，也不会与其他项目冲突；
• 无导入期问题：依赖在服务器导入前完成安装；
• IDE 支持：JSON Schema 提供自动补全与校验；
• 可共享：完整的服务器配置可以随文件直接分享，实现跨环境、跨团队的复现式部署，从本地开发到生产服务器保持一致。

若想看到更多不同规模的配置示例，可继续阅读 server-configuration 官方文档（含基础、开发、生产、数据科学、多环境五套完整示例），或参考仓库中 fastmcp_config 目录下的full_example.fastmcp.json与 mcp_server_config_schema 测试 了解字段校验行为。

【免费下载链接】fastmcp🚀 The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp