FastMCP服务器参数：启动配置的完整参考

2026-02-04 04:09:20作者：何将鹤

还在为FastMCP服务器启动参数而烦恼？每次部署都要翻文档查参数？本文将为你提供FastMCP服务器启动配置的完整参考，涵盖所有参数、配置方法和最佳实践，让你一次掌握所有启动选项！

🎯 读完本文你将获得

✅ FastMCP服务器启动参数的完整清单
✅ 三种传输协议的详细配置指南
✅ fastmcp.json配置文件的完整用法
✅ 环境变量和依赖管理的专业配置
✅ 生产环境部署的最佳实践
✅ CLI命令与配置文件的无缝切换

📋 核心启动参数总览

FastMCP服务器支持两种启动方式：直接调用run()方法和使用fastmcp.json配置文件。以下是所有可用参数的完整参考：

传输协议参数

参数	类型	默认值	描述	适用传输
`transport`	`str`	`"stdio"`	传输协议类型	所有
`host`	`str`	`"127.0.0.1"`	绑定主机地址	HTTP/SSE
`port`	`int`	`3000`	绑定端口号	HTTP/SSE
`path`	`str`	`"/mcp/"`	MCP端点路径	HTTP
`show_banner`	`bool`	`true`	显示启动横幅	所有

日志与调试参数

参数	类型	默认值	描述
`log_level`	`str`	`"INFO"`	日志级别：DEBUG/INFO/WARNING/ERROR/CRITICAL
`debug`	`bool`	`false`	调试模式（已弃用）

🚀 三种传输协议的详细配置

1. STDIO传输（默认）

STDIO（Standard Input/Output）是默认传输协议，适用于本地开发和桌面应用集成。

from fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool
def hello(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    # 默认STDIO传输
    mcp.run()
    
    # 显式指定STDIO
    mcp.run(transport="stdio")

适用场景：

Claude Desktop集成
命令行工具开发
本地测试和调试
单用户应用程序

2. HTTP传输（推荐）

HTTP传输将服务器转换为网络服务，支持多客户端并发访问。

if __name__ == "__main__":
    # 基础HTTP配置
    mcp.run(
        transport="http",
        host="127.0.0.1",    # 本地访问
        port=8000,           # 端口号
        path="/api/mcp/",    # 自定义路径
        log_level="DEBUG"    # 调试日志
    )
    
    # 生产环境配置
    mcp.run(
        transport="http",
        host="0.0.0.0",      # 所有网络接口
        port=3000,
        log_level="INFO"
    )

网络配置选项：

host="127.0.0.1" - 仅本地访问（开发）
host="0.0.0.0" - 所有网络接口（生产）
port - 端口号（3000-65535）
path - URL路径端点

3. SSE传输（传统）

SSE（Server-Sent Events）是传统的HTTP传输协议，仅建议用于向后兼容。

if __name__ == "__main__":
    mcp.run(
        transport="sse",
        host="127.0.0.1",
        port=8000
    )

⚠️ 注意：SSE传输已不推荐使用，请优先选择HTTP传输。

📁 fastmcp.json配置文件详解

FastMCP 2.12.0+ 引入了声明式配置文件，这是推荐的配置方式。

配置文件结构

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

Source配置（必需）

"source": {
  "type": "filesystem",
  "path": "src/server.py",
  "entrypoint": "mcp"
}

字段	类型	必需	描述
`type`	`string`	否	源类型（目前仅支持`filesystem`）
`path`	`string`	是	Python文件路径
`entrypoint`	`string`	否	服务器实例名称（默认搜索mcp/server/app）

Environment配置

"environment": {
  "python": ">=3.10,<3.12",
  "dependencies": ["pandas>=2.0", "requests", "httpx"],
  "requirements": "requirements.txt",
  "editable": ["."],
  "project": "."
}

Python版本约束：

"3.11" - 精确版本
">=3.10" - 最小版本
">=3.10,<3.13" - 版本范围

依赖管理：

dependencies - 直接包列表
requirements - requirements.txt文件路径
editable - 可编辑模式安装的包
project - uv项目目录

Deployment配置

"deployment": {
  "transport": "http",
  "host": "0.0.0.0",
  "port": 3000,
  "path": "/mcp/",
  "log_level": "INFO",
  "env": {
    "API_KEY": "${ENV_API_KEY}",
    "DATABASE_URL": "postgres://${DB_USER}@${DB_HOST}/mydb"
  },
  "cwd": "/app",
  "args": ["--config", "server-config.json"]
}

环境变量插值：

"env": {
  "API_URL": "https://api.${ENVIRONMENT}.example.com",
  "DB_HOST": "${DB_HOST}"
}

运行时替换：${ENVIRONMENT} → 实际环境变量值

🔧 CLI命令与配置文件的配合使用

基本用法

# 自动检测当前目录的fastmcp.json
fastmcp run

# 指定配置文件
fastmcp run production.fastmcp.json

# CLI参数覆盖配置文件
fastmcp run fastmcp.json --port 8080 --log-level DEBUG

环境管理选项

# 跳过环境设置（已有合适环境时）
fastmcp run fastmcp.json --skip-env

# 预构建环境
fastmcp project prepare fastmcp.json --output-dir ./env
fastmcp run fastmcp.json --project ./env

# 传递参数给服务器
fastmcp run server.py -- --config config.json --debug

🏗️ 多环境配置策略

开发环境配置

// dev.fastmcp.json
{
  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
  "source": {
    "path": "src/server.py",
    "entrypoint": "mcp"
  },
  "environment": {
    "python": "3.11",
    "dependencies": ["fastmcp[dev]"],
    "editable": ["."]
  },
  "deployment": {
    "transport": "http",
    "host": "127.0.0.1",
    "port": 8000,
    "log_level": "DEBUG",
    "env": {
      "DEBUG": "true",
      "ENV": "development"
    }
  }
}

生产环境配置

// prod.fastmcp.json
{
  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
  "source": {
    "path": "app/main.py",
    "entrypoint": "mcp_server"
  },
  "environment": {
    "python": "3.11",
    "requirements": "requirements/production.txt"
  },
  "deployment": {
    "transport": "http",
    "host": "0.0.0.0",
    "port": 3000,
    "log_level": "WARNING",
    "env": {
      "ENV": "production",
      "DATABASE_URL": "postgresql://user:pass@db.example.com/prod"
    }
  }
}

📊 配置参数对比表

配置方式	优点	缺点	适用场景
直接run()调用	简单直接，无需额外文件	配置分散，不易维护	快速测试、简单项目
fastmcp.json	集中管理，版本控制友好	需要学习配置语法	生产环境、团队项目
CLI参数覆盖	灵活临时调整	命令复杂，易出错	调试、临时配置变更

🚨 常见问题与解决方案

1. 端口冲突问题

# 检查端口占用
lsof -i :8000

# 使用不同端口
mcp.run(transport="http", port=8080)

2. 权限问题

# 非特权端口（>1024）
mcp.run(port=3000)  # 推荐

# 或者使用sudo（不推荐）
sudo fastmcp run --port 80

3. 环境变量配置

# 配置文件中的环境变量插值
"env": {
  "API_KEY": "${API_KEY}",      # 从系统环境变量获取
  "DB_URL": "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}/db"
}

🎯 最佳实践总结

使用fastmcp.json - 生产环境首选配置方式
环境分离 - 为开发、测试、生产创建不同配置文件
端口选择 - 开发用8000+，生产用3000+
日志分级 - 开发用DEBUG，生产用INFO或WARNING
网络绑定 - 开发用127.0.0.1，生产用0.0.0.0
依赖管理 - 使用requirements.txt确保一致性

💡 进阶技巧

自定义HTTP路由

from fastmcp import FastMCP
from starlette.requests import Request
from starlette.responses import JSONResponse

mcp = FastMCP("MyServer")

@mcp.custom_route("/health", methods=["GET"])
async def health_check(request: Request) -> JSONResponse:
    return JSONResponse({"status": "ok", "version": "1.0.0"})

@mcp.tool
def process_data(data: str) -> str:
    return f"Processed: {data}"

if __name__ == "__main__":
    mcp.run(transport="http", port=8000)

ASGI应用部署

# app.py
from fastmcp import FastMCP

def create_app():
    mcp = FastMCP("MyServer")
    
    @mcp.tool
    def process(data: str) -> str:
        return f"Processed: {data}"
    
    return mcp.http_app()

app = create_app()

# 使用uvicorn运行
# uvicorn app:app --host 0.0.0.0 --port 8000