MCP Forge Python - 准备就绪的生产级MCP服务器模板
](https://www.python.org/downloads/)  ](https://hub.docker.com)     
一个使用Python构建的全面且可投入生产的MCP（模型上下文协议）服务器模板。这是原始MCP Forge Go项目的Python移植版本，具备OAuth 2.0认证、JWT（JSON Web Token）验证功能，并为开发AI驱动应用程序的开发者提供了无缝部署选项。
MCP Forge Python 的关键特性
MCP协议实现
- 用……构建
mcp[cli]支持完整MCP协议的Python库 - 全面的工具、资源和提示实施
- 可配置服务器初始化，包含名称和版本
通信运输
- Stdio Transport 翻译为中文是“标准输入输出传输”或“标准I/O传输”，具体翻译可能根据上下文有所调整。在这里，“Stdio”通常指的是“Standard I/O”（标准输入输出），“Transport”则指的是传输或传输方式本地AI客户端（如Claude Desktop）的标准输入/输出通信
- HTTP 流媒体用于实时网页通信的可流式传输HTTP
内置的MCP工具
服务器包含通过路由器注册的几个MCP工具：
- 你好，世界个性化问候功能（需要
tool:user在HTTP模式下的作用域 - 我是谁基于JWT的用户信息泄露（来自JWT有效载荷）
安全与中间件
- 访问日志记录可配置的请求日志记录，支持头部信息脱敏
- JWT 验证双令牌认证策略
- 使用JWKS URI和CEL表达式进行本地验证 - 外部代理委托（兼容Istio）
- CORS（跨源资源共享）可配置的跨域资源共享
- JWT 上下文在中间件和MCP工具之间安全共享JWT声明
OAuth 2.0 集成（RFC 8414 和 RFC 9728）
- OAuth 授权服务器OpenID Connect 配置代理
- 受保护资源元数据完成OAuth资源发现端点
- OAuth 流程内置用于授权码流程的登录和回调端点
灵活配置
- 基于TOML的配置系统，包含专用部分用于：
- 服务器设置（名称、版本、传输方式） - 中间件配置（日志记录、JWT、CORS） - OAuth 集成（授权服务器、受保护资源） - OAuth 流的认证设置（客户端凭据、重定向 URI） - JWT声明暴露配置
额外的终点（或：额外的端点）
除了MCP协议端点外，服务器还提供：
- GET /服务器信息
- 获取 /health（或“访问 /health 端点”）健康检查端点
- GET /login 翻译为中文是：“获取（访问）/login（登录）页面”启动OAuth授权码流程（重定向到Auth0/Keycloak）
- GET /callback 翻译为中文是：“获取（GET请求）/callback（回调路径）”处理OAuth回调并用代码换取令牌
生产就绪部署
- 使用Dockerfile完成Docker容器化
- 用于云部署的Kubernetes Helm图表
- Keycloak、Istio 和 Hashrouter 的集成指南
系统要求
外部依赖
- python大于等于 3.11
- 紫外线依赖管理和虚拟环境管理器（从...安装 astral.sh/uv 翻译成中文可以是“星界.sh/uv”（这里的“astral”常被翻译为“星界”或“星体的”，而“.sh”和“/uv”作为文件扩展名或路径的一部分，通常不直接翻译，保持原样）。不过，具体翻译可能还需根据上下文或该文件/路径的实际用途来调整。如果这是一个特定软件或脚本的名称，可能需要查找官方翻译或保持原名以避免混淆)
- 仅仅 （可选）：简化版命令执行器（从 just.systems（可译为“正义系统”或根据具体语境调整为更贴切的表述，但“just.systems”本身作为一个专有名词或品牌名，直接翻译可能无法完全传达其原意，因此保留原样或稍作调整以保持其品牌特性）)
- Docker （可选）：用于构建镜像
JWT 策略的要求
- “local”策略需要一个 JWKS 服务器 （如Keycloak、Auth0等OAuth提供者）提供JWKS（JSON Web Key Set）端点以获取公钥并验证令牌。在（相关配置中）进行配置
jwks_uri。 - “external”策略（或“外向型”策略）需要一个 上游代理 （如Istio、Envoy或API网关）验证JWT并在头部转发声明。在MCP中不需要JWKS，但代理必须配置为注入头部（例如。
X-Forwarded-User）。
当地要求
- 生产依赖项：
- fastapiASGI网络框架 - uvicorn[standard]支持HTTP流的ASGI服务器 - pydantic数据验证 - pydantic-settings从文件中配置 - tomli适用于Python 3.11之前的TOML解析器 - mcp[cli]MCP Python SDK - httpx异步HTTP客户端 - PyJWTJWT 处理 - requests同步HTTP客户端 - cryptography加密操作
- 开发依赖项：
- ruff代码检查和格式化 - pyright类型检查 - pytest测试框架 - pytest-asyncio为 pytest 提供异步支持 - coverage代码覆盖率 - pytest-benchmark性能基准测试
安装与设置
# Install dependencies
uv sync
# Install package (enables direct commands)
uv pip install -e .
# Run HTTP server with streaming
uv run http
# Alternative: Run stdio server for local AI clients
uv run stdio开发命令
# Testing & Quality
just test # Run all tests
just cov # Run tests with coverage report
just bench # Run benchmarks
just lint # Lint and format code
just typing # Type checking
just check-all # Run all quality checks
# Lifecycle
just install # Install/update dependencies
just update # Update dependencies to latest versions
just clean # Remove all temporary files (.venv, caches, dist)
just clean-cache # Clean caches only (keep .venv)
just fresh # Clean + fresh install
# Running
just run # Run HTTP server
just run-stdio # Run stdio mode
just dev-http # Run HTTP server with MCP Inspector
just dev-stdio # Run stdio server with MCP Inspector注用于开发，请使用 uv pip install -e . 用于可编辑安装。支持的传输方式
- HTTP 流媒体对于像Claude Web这样的远程客户端。终端
/mcp使用HTTP流进行运行uv run http。 - Stdio（注：这通常指的是标准输入输出库，但在中文语境下，我们直接使用其功能描述或保持原样，因为“Stdio”本身是一个专有名词，没有直接的中文翻译）对于像Claude Desktop这样的本地客户端，请使用以下方式运行：
uv run stdio。
JWT 配置
JWT 中间件支持两种验证策略：
“local”策略
- 在MCP服务器上直接验证JWT。
- 从JWKS端点下载公钥（在配置中指定）
jwks_uri）。 - 支持可配置的缓存和CEL（可能是指某种条件表达式语言或逻辑）条件，以实现高级权限管理。
- MCP工具检查所需的范围（例如。，
tool:user（用于 hello_world）。 - 要求带有JWKS端点的OAuth服务器（例如Keycloak）。
“外部”策略
- 将验证委托给上游代理（如Istio、Envoy等）。
- JWT 被转发到一个特定的头部（
forwarded_header）。 - 代理验证并提取声明，将其注入到请求中。
- 要求已配置代理用于JWT验证和头部转发。
示例在 config.toml。
配置
请看 config.toml 作为配置示例。
认证配置
对于OAuth流程，请配置auth部分：
[auth]
client_id = "your-client-id"
client_secret = "your-client-secret"
redirect_uri = "http://localhost:8080/callback"CORS 配置
配置跨域资源共享：
[middleware.cors]
allow_origins = ["https://yourdomain.com", "http://localhost:3000"]
allow_credentials = true
allow_methods = ["GET", "POST", "PUT", "DELETE"]
allow_headers = ["*"]JWT声明泄露
控制哪些JWT声明可供MCP工具访问：
# Expose all claims (not recommended for production)
jwt_exposed_claims = "all"
# Or expose only specific claims
jwt_exposed_claims = ["user_id", "email", "roles"]注： roles 并且 scope 声明总是为了授权目的而公开。
安全注意事项默认情况下，服务器运行在 127.0.0.1 以避免不必要的暴露。配置主机和端口 config.toml 在……下面 [server.transport.http]改为 0.0.0.0 仅在必要时，并采取适当的安全措施。
安全考虑因素
此模板实施了多项安全措施，以防范常见漏洞。作为模板，它被设计为可针对不同部署场景进行配置。
JWT声明泄露
为了最小化数据暴露，配置哪些JWT声明可供MCP工具访问：
jwt_exposed_claims = ["user_id", "roles"] # Only expose specific claims
# or
jwt_exposed_claims = "all" # Expose all claims (not recommended for production)注： roles 并且 scope 无论此配置如何，声明始终会为授权目的而公开。
访问日志记录
敏感头信息在日志中会自动进行遮蔽处理：
[logging]
redacted_headers = ["Authorization", "X-API-Key", "Cookie"]
max_body_size = 1024 # Limit logged body size速率限制
为JWT（JSON Web Token）验证实施了基本速率限制，以防止暴力破解攻击。
URI验证
OAuth和JWKS URI会与白名单域名进行验证，以防止SSRF攻击。
确保依赖项安全
依赖项会定期更新以修复已知漏洞。运行 uv lock --upgrade 更新到最新的安全版本。
生产检查清单
- 使用适当的代理（Istio、Envoy）与“外部”JWT 策略
- 配置最小暴露声明
- 启用带有内容遮蔽的访问日志记录
- 验证所有URI是否属于受信任的域名
- 保持依赖项更新
- 定期进行安全测试
文档
项目架构
src/mcp_app/
├── main.py # Application entry point and FastAPI setup
├── config.py # Pydantic configuration models
├── context.py # JWT context management for secure claim sharing
├── handlers/ # OAuth endpoints handlers (RFC 8414 & RFC 9728)
├── middlewares/ # Custom middlewares (JWT, access logs, CORS)
└── tools/ # MCP tools and registration router核心组件
- main.py（主程序文件）初始化FastMCP服务器、FastAPI应用、中间件以及OAuth端点
- config.py（配置文件）基于 TOML 的配置与 Pydantic 模型
- \
context.py\翻译为中文是：“上下文.py” 或者根据具体用途，也可以翻译为“环境配置.py”（如果该文件用于设置或管理某种环境或上下文配置的话）。但通常情况下，“context”在编程中直接翻译为“上下文”更为常见和准确中间件与工具之间异步安全的JWT上下文共享 - 处理程序/OAuth授权服务器和受保护资源的元数据端点
- 中间件/JWT验证、访问日志记录和CORS处理
- 工具/MCP工具实现及注册系统
发展
如需详细的开发说明，包括如何将此项目用作您自己的MCP服务器的模板，请参阅 DEVELOPMENT.md 翻译为中文是：“开发说明.md” 或者 “开发文档.md”（具体翻译可能根据上下文有所调整，但“md”通常表示Markdown格式的文件，所以“开发说明.md”或“开发文档.md”是比较常见的译法）。
贡献；助力
我们欢迎投稿！请参阅 CONTRIBUTING.md（贡献指南文件） 关于如何为该项目做出贡献的指南。
更新日志
看见 CHANGELOG.md 翻译为中文是：“变更日志文件（Markdown 格式）” 查看更改和发布版本的列表。
许可证
这个项目采用无许可协议（Unlicense）授权——详见 许可证 详情请查阅文件。
功劳/学分/认可
这是该（软件/程序）的Python版本移植 MCP Forge（注：MCP通常指“Mod Development Kit”（模组开发工具包），但在此上下文中，若“Forge”指的是与MCP相关的某个特定工具或平台，则“MCP Forge”可直译为“MCP锻造工具/平台”，具体翻译需根据上下文确定） 项目（Go语言），在保持安全标准的同时，扩展了额外的OAuth流程端点以及Python特有的实现。