abwaters/mcp-zero

# mcp-zero [](https://github.com/abwaters/mcp-zero/actions/workflows/ci.yml) [](https://github.com/abwaters/mcp-zero/actions/workflows/codeql.yml) [](https://securityscorecards.dev/viewer/?uri=github.com/abwaters/mcp-zero) [](LICENSE) [](pyproject.toml) 一个开源网关，部署在您的企业 AI 工具与 MCP 服务器之间，旨在落实合规团队在批准采用 [MCP](https://modelcontextprotocol.io) 之前所要求的各项安全控制。 若没有它，AI 工具可以调用任何 MCP 服务器，缺乏访问控制，没有审计跟踪，也没有数据保护——这在受监管的环境中是完全不可行的。mcp-zero 补齐了缺失的治理层：它会验证用户身份、检查策略规则、对敏感数据进行脱敏，并记录每一个操作——所有这些都在线进行，发生在请求到达下游服务器之前。 将其部署为单一的 Python 服务。使用 YAML 策略文件进行配置。无需安装代理，无 SaaS 依赖，无供应商锁定。 ``` Enterprise AI Tool ──► MCP Gateway ──► MCP Servers │ ┌──────────┴──────────┐ │ Hook Pipeline │ │ │ │ Identity (core) │ │ Governance (core) │ │ ◇ Plugins (ext) │ │ Audit (core) │ └─────────────────────┘ ``` ## 功能 - **身份验证** — Okta OAuth2 JWT 验证，支持可配置的声明映射（`user_id`、`email`、`groups`） - **治理** — YAML 策略文件，包含作用域涵盖服务器、工具、用户和组的默认拒绝规则 - **数据保护** — 通过 Microsoft Presidio 对输入和输出进行内联 PII 和密钥脱敏 - **审计** — 结构化日志，包含用户归属、关联 ID 和策略决策 - **传输** — 可流式传输的 HTTP（主要方式）、传统的入站 SSE（可选），以及在同一个策略 pipeline 下支持上游 HTTP/SSE/stdio 服务器连接 - **Pipeline** — 基于 hook 的请求生命周期，支持有序执行和短路机制 - **插件** — 基于 entry-point 的插件架构，可通过自定义 hook（如脱敏、限流、指标等）扩展 pipeline ## 快速开始 ### 前置条件 - Python 3.12+ - 一个 Okta 租户（用于身份验证） ### 安全提示 **重要**：网关设计为默认故障关闭，但需要进行正确的配置以实施安全控制： - **强烈推荐使用策略文件**：设置 `MCP_POLICY_FILE` 以启用治理和插件配置。 - **默认启动时故障关闭**：如果既未配置身份验证也未配置策略文件，网关将以退出代码 78 退出。 - **仅供开发环境的绕过方式**： - `MCP_RELAX_STARTUP_CHECKS=true` 允许在没有安全控制的情况下启动。 - `MCP_SKIP_TLS_VALIDATION=true` 允许使用非 HTTPS 的身份验证/服务器/OBO URL。 - **严格的生产环境加固**：`MCP_STRICT_SECURITY=true` 要求身份验证和治理同时处于激活状态。 - **脱敏依赖项**：Presidio 脱敏需要 `presidio-analyzer` 和 `presidio-anonymizer`（默认安装中已包含）。 **已知限制**（更广泛的分析请参阅[安全审查](docs/security_review_mcp_gateway.md)）： - 传统/开发模式仍然可以通过 `MCP_RELAX_STARTUP_CHECKS=true` 和/或 `MCP_SKIP_TLS_VALIDATION=true` 被有意启用；绝不能在生产环境中使用这些配置。 - OBO token 交换需要明确的环境变量（`OKTA_TOKEN_ENDPOINT`、`OKTA_CLIENT_ID`、`OKTA_CLIENT_SECRET`）以及基于服务器的策略配置。 - 入站 SSE 支持出于兼容性目的仍然保留，但已被弃用；如果不需要，请使用 `MCP_SSE_ENABLED=false` 禁用。 绝不要在放宽启动检查或禁用 TLS 验证的情况下运行生产部署。 ### 安装 ``` # Clone 和 install git clone https://github.com/abwaters/mcp-zero.git cd mcp-zero python -m venv .venv # Linux/macOS source .venv/bin/activate # Windows .venv\Scripts\activate pip install -e ".[dev]" ``` 在 Windows 上，提供了便捷脚本： ``` scripts\install.bat # Creates venv and installs everything ``` ### 配置 创建一个策略文件（例如 `policy.yaml`）： ``` version: 1 default: deny identity: provider: okta issuer: https://your-org.okta.com audience: your-app-audience servers: - name: my-mcp-server transport: http url: https://mcp-server.internal.corp/mcp policies: - id: allow-devs description: Allow developers to use read tools effect: allow subjects: groups: - developers mcp_servers: - name: my-mcp-server tools: - read_* - list_* masking: presidio: enabled: true entities: - PERSON - EMAIL_ADDRESS - PHONE_NUMBER - CREDIT_CARD - API_KEY - PASSWORD ``` ### 运行 ``` # 设置 policy 文件路径 export MCP_POLICY_FILE=policy.yaml # 启动 gateway python -m mcp_zero # 或 mcp-zero ``` 或者对于简单的设置，可以使用环境变量： ``` export MCP_UPSTREAM_URL=http://localhost:9000 export OKTA_ISSUER=https://your-org.okta.com export OKTA_AUDIENCE=your-app-audience python -m mcp_zero ``` 网关默认在 `0.0.0.0:8080` 上启动（可通过 `MCP_HOST` 和 `MCP_PORT` 配置）。 ## 配置说明 ### 环境变量 | 变量 | 描述 | 默认值 | |---|---|---| | `MCP_POLICY_FILE` | YAML/JSON 策略文件的路径 | _(无)_ | | `MCP_UPSTREAM_URL` | 单个上游 MCP 服务器 URL（传统回退） | _(无)_ | | `MCP_HOST` | 网关绑定的主机 | `0.0.0.0` | | `MCP_PORT` | 网关绑定的端口 | `8080` | | `MCP_RELAX_STARTUP_CHECKS` | 允许在没有必要安全控制的情况下启动（仅限开发/测试） | `false` | | `MCP_SKIP_TLS_VALIDATION` | 允许 `http://` issuer/服务器/OBO URL（仅限开发/测试） | `false` | | `MCP_STRICT_SECURITY` | 启动时要求身份验证和治理并存 | `false` | | `MCP_SSE_ENABLED` | 启用已弃用的入站 SSE endpoint（`/mcp/sse*`） | `true` | | `LOG_LEVEL` | 日志级别 (DEBUG, INFO, WARNING, ERROR) | `INFO` | | `LOG_FORMAT` | 日志输出格式 (`json` 或 `text`) | `json` | | `OKTA_ISSUER` | Okta token issuer URL（无策略文件时的回退选项） | _(无)_ | | `OKTA_AUDIENCE` | 预期的 JWT audience 声明（无策略文件时的回退选项） | _(无)_ | | `OKTA_TOKEN_ENDPOINT` | Okta token 交换 endpoint（用于 OBO） | _(无)_ | | `OKTA_CLIENT_ID` | 网关 client ID（用于 OBO） | _(无)_ | | `OKTA_CLIENT_SECRET` | 网关 client secret（用于 OBO） | _(无)_ | | `ANALYTICS_REDIS_URL` | Redis 连接 URL（设置后启用分析功能） | _(无)_ | | `ANALYTICS_REDIS_CLUSTER` | 使用 Redis Cluster 客户端 | `false` | | `ANALYTICS_REDIS_PASSWORD` | Redis 身份验证密码 | _(无)_ | | `ANALYTICS_ENVIRONMENT` | 分析功能的关键 namespace（例如 `production`） | `default` | | `ANALYTICS_GATEWAY_ID` | 唯一的网关实例 ID | _(自动生成)_ | | `ANALYTICS_KEY_PREFIX` | 用于分析的 Redis key 前缀 | `mcpgw` | | `ANALYTICS_RETENTION_SECONDS` | 分析 key 的 TTL（以秒为单位） | `3600` | | `MCP_CORS_ORIGINS` | 逗号分隔的允许 CORS 源（设置后启用 CORS） | _(无)_ | | `MCP_CORS_ALLOW_CREDENTIALS` | 允许在 CORS 请求中携带凭证 | `false` | | `MCP_CORS_MAX_AGE` | 预检缓存时长（以秒为单位） | `600` | 当设置了 `MCP_POLICY_FILE` 时，其身份验证部分的优先级高于 `OKTA_*` 环境变量。CORS 和分析相关的环境变量会覆盖策略文件中的值。 ### 策略文件 完整且带有注解的示例请参阅 [`docs/enterprise_mcp_gateway_policy_schema_example.md`](docs/enterprise_mcp_gateway_policy_schema_example.md)。 可运行的示例位于 [`policies/`](policies/) 目录中： | 文件 | 描述 | |------|-------------| | [`policies/everything.yaml`](policies/everything.yaml) | 使用 `@modelcontextprotocol/server-everything` 的 stdio transport | | [`policies/filesystem.yaml`](policies/filesystem.yaml) | 使用 `@modelcontextprotocol/server-filesystem` 的 stdio transport | | [`policies/filesystem-redacted.yaml`](policies/filesystem-redacted.yaml) | 带有 Presidio 脱敏插件的文件系统服务器 | | [`policies/time.yaml`](policies/time.yaml) | 使用 `@modelcontextprotocol/server-time` 的 stdio transport | | [`policies/all.yaml`](policies/all.yaml) | 组合多个 stdio 服务器 | | [`policies/remote-github.yaml`](policies/remote-github.yaml) | 通过可流式传输的 HTTP 访问远程 GitHub MCP 服务器 | | [`policies/remote-github-readonly.yaml`](policies/remote-github-readonly.yaml) | 带有显式只读工具白名单的 GitHub 服务器 | 核心概念： - **`version`**：必须为 `1` - **`default`**：`deny`（拒绝，推荐）或 `allow`（允许） - **`servers`**：下游 MCP 服务器定义（HTTP 或 stdio） - **`policies`**：自上而下评估的有序规则；显式拒绝优先于允许 - **`cors`**：面向基于浏览器客户端的 CORS 配置（默认禁用） - **`masking`**：Presidio 实体检测配置（传统方式 — 请参阅下文的 `plugins`） - **`plugins`**：用于扩展 pipeline hook（脱敏、限流等）的插件声明 #### CORS 配置 在策略文件中添加 `cors` 部分以允许基于浏览器的 MCP 客户端： ``` cors: allow_origins: - https://web-ide.corp.com - https://dashboard.corp.com allow_methods: ["GET", "POST", "OPTIONS"] allow_headers: ["Authorization", "Content-Type"] allow_credentials: false max_age: 600 ``` CORS 默认禁用（故障关闭）。只有 `allow_origins` 是必需的；所有其他字段都具有安全的默认值。环境变量（`MCP_CORS_ORIGINS`、`MCP_CORS_ALLOW_CREDENTIALS`、`MCP_CORS_MAX_AGE`）会覆盖策略文件中的值。 ### 服务器类型 **HTTP 服务器** — 通过可流式传输的 HTTP 访问的远程 MCP 服务器： ``` servers: - name: remote-api transport: http url: https://mcp-server.corp/mcp ``` **SSE 服务器** — 通过 SSE 访问的远程 MCP 服务器： ``` servers: - name: legacy-sse-server transport: sse url: https://mcp-server.corp/sse ``` **stdio 服务器** — 由网关生成并管理的本地进程（在策略文件中配置）： ``` servers: - name: local-filesystem transport: stdio command: npx args: - -y - "@modelcontextprotocol/server-filesystem" - /workspace env: NODE_ENV: production ``` ## 开发 ``` # 运行 tests python -m pytest # all tests python -m pytest tests/masking/ -v # specific module python -m pytest tests/test_main.py -v # specific file # Lint 和 format ruff check src tests ruff format src tests # 运行 gateway python -m mcp_zero ``` 在 Windows 上，请使用提供的脚本： ``` scripts\test.bat # Run tests scripts\lint.bat # Lint scripts\format.bat # Format scripts\run.bat # Run gateway ``` ### 项目结构 ``` src/mcp_zero/ ├── main.py # Application entry point ├── plugin.py # Plugin protocol and base class ├── plugin_manager.py # Plugin discovery and lifecycle ├── context.py # RequestContext, HookContext, UserIdentity ├── identity/ # Okta JWT validation, OBO token exchange ├── governance/ # Policy loading, evaluation, enforcement ├── masking/ # Masking engine interface and hook ├── plugins/ # Built-in plugins (Presidio masking, GitHub repo filter) ├── pipeline/ # Hook lifecycle, registry, execution ├── proxy/ # Starlette app, server management, tool routing ├── analytics/ # Optional Redis-based analytics └── transport/ # HTTP, SSE, and stdio MCP transport clients ``` ### 架构 网关采用基于 hook 的 pipeline 并配备插件系统。核心 hook 负责处理身份验证、治理和审计。其他所有功能——脱敏、限流、指标——都是从策略文件加载的插件。 **核心 hook**（始终存在）： | 优先级 | Hook | 阶段 | 目的 | |----------|------|-------|---------| | 10 | IdentityHook | PRE_VALIDATION | 验证 JWT，解析用户身份 | | 50 | GovernanceHook | POST_VALIDATION | 评估策略规则，允许或拒绝 | | 145 | AnalyticsHook | PRE_AUDIT | 将指标记录到 Redis（如果已配置） | | 150 | AuditHook | PRE_AUDIT | 输出包含完整请求上下文的结构化日志 | **插件 hook**（从策略文件的 `plugins:` 部分加载）： | 优先级范围 | 插槽 | 示例 | |----------------|------|---------| | 20–49 | 治理前 | 限流，请求验证 | | 70–99 | 治理后 | 脱敏（Presidio 在 75），转换 | | 100–139 | 通用 | 指标，缓存，自定义 hook | Hook 按优先级顺序执行。任何 hook 都可以对 pipeline 进行短路处理（例如，治理拒绝会立即停止处理）。 **插件系统**：插件通过 Python entry points（`mcp_zero.plugins` 组）发现，在策略文件中配置，并在启动时注册到 pipeline 中。详情请参阅 [`docs/plugin-architecture-design.md`](docs/plugin-architecture-design.md)。 ## 文档 | 文档 | 描述 | |---|---| | [`docs/quickstart.md`](docs/quickstart.md) | 包含 Docker Compose 和本地路径的分步快速入门 | | [`docs/prd.md`](docs/prd.md) | 产品需求和验收标准 | | [`docs/enterprise_mcp_gateway_architecture_diagram.md`](docs/enterprise_mcp_gateway_architecture_diagram.md) | 包含组件图的逻辑架构 | | [`docs/enterprise_mcp_gateway_implementation_plan_epics.md`](docs/enterprise_mcp_gateway_implementation_plan_epics.md) | 分阶段实施计划 | | [`docs/enterprise_mcp_gateway_policy_schema_example.md`](docs/enterprise_mcp_gateway_policy_schema_example.md) | 带有完整注解的策略文件示例 | | [`docs/enterprise_mcp_gateway_security_compliance_positioning.md`](docs/enterprise_mcp_gateway_security_compliance_positioning.md) | 安全控制与合规对齐 | | [`docs/enterprise_mcp_gateway_threat_model_canvas.md`](docs/enterprise_mcp_gateway_threat_model_canvas.md) | 威胁模型与缓解措施 | | [`docs/ok_obo_for_an_enterprise_mcp_gateway.md`](docs/okta_obo_for_an_enterprise_mcp_gateway.md) | OBO token 交换深度解析 | | [`docs/enterprise_mcp_gateway_leadership_explainer.md`](docs/enterprise_mcp_gateway_leadership_explainer.md) | 面向非技术利益相关者的概述 | | [`docs/configuration-architecture.md`](docs/configuration-architecture.md) | 配置加载、环境变量、策略 schema、优先级规则 | | [`docs/cors-configuration.md`](docs/cors-configuration.md) | 面向基于浏览器 MCP 客户端的 CORS 设置 | | [`docs/plugins/`](docs/plugins/) | 插件快速入门及各插件文档 | ## 对比 mcp-zero 与其他 MCP 网关的对比： | 功能 | mcp-zero | [AgentGateway](https://github.com/agentgateway/agentgateway) | [MintMCP](https://www.mintmcp.com/) | [Microsoft MCP Gateway](https://github.com/microsoft/mcp-gateway) | [Lasso MCP Gateway](https://github.com/lasso-security/mcp-gateway) | |---|---|---|---|---|---| | **许可证** | ✅ MIT | ✅ Apache 2.0 (Linux Foundation) | ❌ 商业 SaaS | ✅ MIT | ✅ MIT | | **语言** | Python | Rust / Go | 专有 | .NET / C# | Python | | **传输** | ✅ 可流式传输的 HTTP, stdio | ✅ 可流式传输的 HTTP, SSE, stdio | ✅ HTTP, SSE, stdio | 仅可流式传输的 HTTP | 仅 stdio | | **身份验证** | ✅ Okta OAuth2 JWT | ✅ JWT, API keys, OAuth (Auth0, Keycloak), MCP auth spec | ✅ OAuth 2.0, SAML, SSO (Okta, Azure AD) | Azure Entra ID / OAuth 2.0 | ❌ 无内置 | | **治理** | ✅ YAML/JSON 策略文件, 默认拒绝, 服务器/工具/用户/组规则 | ✅ RBAC, Cedar 策略引擎, 限流 | RBAC/ABAC, 基于 Virtual MCP 角色的 endpoint | 通过 Entra ID 角色实现 RBAC | ❌ 仅支持基于插件 | | **数据保护** | ✅ 对输入和输出进行内联 Presidio 脱敏 | ❌ 无内置 | ✅ PII 修正，密钥扫描，内容过滤 | ❌ 无内置 | Presidio PII + 正则密钥脱敏 | | **审计** | ✅ 带有用户归属、关联 ID、策略决策的结构化日志 | ✅ OpenTelemetry 指标，日志，分布式追踪 | ✅ 不可变审计跟踪，仪表盘，SOC 2 | Azure Application Insights | 基于 SQLite 的工具调用追踪 | | **部署** | ✅ 自托管，轻量级 | ✅ 自托管（二进制，Docker，Kubernetes） | 托管云 SaaS（提供自托管） | 在 Kubernetes (AKS) 上自托管 | 本地代理进程 | | **多租户** | ✅ 用户/组级别的策略 | ✅ 多租户及按租户资源 | ✅ 基于角色的 endpoint | ✅ 资源级别的 RBAC | ❌ 单用户本地代理 | | **主要焦点** | 面向受监管企业的治理与数据保护 | 面向大规模 Agentic AI 的高性能连接性与可观测性 | 托管治理 + 部署平台 | 可扩展的 Kubernetes 路由 + 生命周期管理 | 面向本地 MCP 使用的安全护栏 | ### 何时选择什么 - **mcp-zero** — 您需要一个自托管、轻量级的网关，支持 policy-as-code 治理、内联 PII 脱敏以及用于合规的结构化审计日志。无供应商锁定，无云依赖。 - **AgentGateway** — 您需要一个基于 Rust 的高性能代理，用于大规模的 agent-to-agent 和 agent-to-tool 连接，并具备 OpenTelemetry 可观测性和基于 Cedar 的策略。如果您在 MCP 之外还需要 A2A 协议支持或 LLM 网关路由，这将非常合适。无内置 PII 脱敏。 - **MintMCP** — 您希望拥有一个托管的 SaaS 平台，以最少的运维开销处理部署、托管和治理。需要为商业许可做预算。 - **Microsoft MCP Gateway** — 您已经使用了 Azure/AKS，并且需要结合 Entra ID 集成的 Kubernetes 原生 MCP 服务器编排。需自带数据保护和策略引擎。 - **Lasso MCP Gateway** — 您需要一个专注于为个人开发者工作站进行密钥/PII 脱敏的轻量级本地代理。高级功能需要商业版 Lasso 平台。 ## 许可证 详情请参阅 [LICENSE](LICENSE)。

标签：AI安全, Chat Copilot, MCP网关, Python, Streamlit, 审计日志, 搜索引擎查询, 数据治理, 无后门, 访问控制, 逆向工具