OpenZiti Network Management

Ziti MCP 服务由 NetFoundry 赞助，是其安全工作负载和智能体计算解决方案组合的一部分。 NetFoundry 是 OpenZiti 和 zrok 的创建者。

MCP（模型上下文协议） 是 Anthropic 推出的一种开放协议，用于标准化大模型与外部工具、资源或远程服务之间的通信方式。

Ziti MCP 服务与大模型和 AI Agent 集成，让你可以使用自然语言执行各种 Ziti 网络管理操作。例如，你只需让 Claude Desktop 执行 Ziti 管理操作即可：

• 列出已有的身份

• 告诉我网络中是否存在任何暴露

• 你发现了潜在的配置错误吗？

• 哪些身份可以访问 Demo1 服务？

• 创建一个名为“Demo”的新 Ziti 身份并获取其 ID

• 使用 UPDB 登录我的生产 Ziti 网络

• 切换到预发布网络

• 等等。

🚀 快速入门

前置条件：

• Claude Desktop 或任何其他 MCP 客户端
• OpenZiti 网络
• Go 1.24+（仅在从源代码构建时需要）

安装

下载预编译二进制文件

macOS、Linux 和 Windows（amd64 和 arm64）的预编译二进制文件可在发布页面下载。

macOS（Apple Silicon）

curl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_darwin_arm64.tar.gz | tar xz
sudo mv ziti-mcp-server /usr/local/bin/

macOS（Intel）

curl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_darwin_amd64.tar.gz | tar xz
sudo mv ziti-mcp-server /usr/local/bin/

Linux（amd64）

curl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_linux_amd64.tar.gz | tar xz
sudo mv ziti-mcp-server /usr/local/bin/

Linux（arm64）

curl -sL https://github.com/openziti/ziti-mcp-server/releases/latest/download/ziti-mcp-server_linux_arm64.tar.gz | tar xz
sudo mv ziti-mcp-server /usr/local/bin/

Windows

从发布页面下载相应的 .zip 文件，并将解压后的 ziti-mcp-server.exe 添加到 PATH。

从源代码构建

go install github.com/openziti/ziti-mcp-server/cmd/ziti-mcp-server@latest

注册到 AI 客户端

使用 install 将 Ziti MCP 服务注册到 AI 客户端。这只会更新客户端的配置文件，不会进行身份验证。请使用运行时登录工具或 init 进行身份验证。

# Register with Claude Desktop (default)
ziti-mcp-server install

# Register with a specific client
ziti-mcp-server install --client claude-code
ziti-mcp-server install --client cursor
ziti-mcp-server install --client windsurf
ziti-mcp-server install --client vscode
ziti-mcp-server install --client warp

# Register with read-only tools only
ziti-mcp-server install --read-only

# Register with specific tool patterns
ziti-mcp-server install --tools '*Identit*,list*'

安装完成后，重启 AI 客户端，并使用运行时登录工具进行身份验证（例如，询问：“使用用户名 admin 登录我位于 ctrl.example.com 的 Ziti 网络”）。

启动并登录

服务可以在未进行任何预先配置的情况下启动。AI Agent 可以在运行时使用内置的登录工具登录网络：

ziti-mcp-server run

然后在 AI 客户端中直接询问：

使用用户名 admin 和密码 admin 登录我位于 192.168.1.100:1280 的 Ziti 网络

对于非交互式或自动化设置，请使用 init 在启动前预先配置凭据：

ziti-mcp-server init \
  --auth-mode updb \
  --ziti-controller-host <your-controller-host> \
  --username <username> \
  --password <password> \
  --profile prod

请参阅身份验证，了解所有支持的模式（UPDB、设备身份验证、客户端凭据、身份文件）。

手动配置客户端

install 命令会自动处理客户端配置。如果需要手动配置 MCP 客户端，请将以下内容添加到其配置中并重启：

{
  "mcpServers": {
    "ziti": {
      "command": "/path/to/ziti-mcp-server",
      "args": ["run"],
      "capabilities": ["tools"],
      "env": {
        "OPENZITI_MCP_DEBUG": "true"
      }
    }
  }
}

你可以在 args 数组中添加 --tools '<pattern>' 和/或 --read-only，以控制可用的工具。请参阅限制工具访问。

验证集成

重启 MCP 客户端（Claude Desktop、Windsurf、Cursor、Warp 等），并让它协助你管理 Ziti 网络。

🕸️ 架构

Ziti MCP Server 实现了 Model Context Protocol，使客户端（如 Claude）能够：

1. 请求可用 Ziti 工具的列表
2. 使用参数调用特定工具
3. 接收来自 Ziti Management API 的结构化响应

该服务负责身份验证、请求验证，以及与 Ziti Management API 的安全通信。

说明

该服务以本地进程的形式运行，并连接到 Claude Desktop，从而实现安全通信，同时不暴露你的 Ziti 凭据。

🔐 身份验证

Ziti MCP Server 使用 Ziti Management API，需要通过身份验证才能访问你的 Ziti 网络。

身份验证模式

该服务支持四种身份验证模式：

UPDB 模式（用户名/密码）

使用此模式，通过用户名/密码直接向 Ziti 控制器进行身份验证：

ziti-mcp-server init \
  --auth-mode updb \
  --ziti-controller-host <your-controller-host> \
  --username <username> \
  --password <password>

或者在运行时通过 AI Agent 使用 loginUpdb 工具进行身份验证。

设备身份验证模式（交互式登录）

使用此模式通过浏览器交互式登录。推荐用于开发和面向用户的场景：

ziti-mcp-server init \
  --auth-mode device-auth \
  --ziti-controller-host <your-controller-host> \
  --idp-domain <your-idp-domain> \
  --idp-client-id <your-client-id> \
  --idp-audience <your-audience>

或者在运行时通过 loginDeviceAuth 工具进行身份验证（该工具会返回验证 URL 供用户访问，然后使用 completeLogin 完成登录）。

客户端凭据模式（服务帐户）

使用此模式进行服务帐户身份验证和自动化操作。推荐用于生产环境：

说明

将令牌生命周期缩短到尽可能低，以降低安全风险。了解更多

ziti-mcp-server init \
  --auth-mode client-credentials \
  --ziti-controller-host <your-controller-host> \
  --idp-domain <your-idp-domain> \
  --idp-client-id <your-client-id> \
  --idp-client-secret <your-client-secret>

身份文件模式（mTLS 证书）

使用此模式，通过 Ziti 身份 JSON 文件进行基于证书的身份验证。无需配置 IdP：

ziti-mcp-server init \
  --auth-mode identity \
  --identity-file <path-to-identity.json>

身份文件是标准的 Ziti 身份 JSON 文件，其中包含 ztAPI、id.cert、id.key 和 id.ca 字段。证书内容会被提取并存储在配置文件中。成功执行 init 后，可以删除身份文件（如有需要，以进一步增强安全性）。

重要

使用 CLI init 时，以下情况都需要运行该命令：

• 首次设置 MCP Server
• 已从之前的会话注销
• 要切换到其他 Ziti 网络
• 令牌已过期

或者，使用运行时登录工具（loginUpdb 等）进行身份验证，无需重启服务。

多配置文件支持

该服务支持多个命名网络配置文件，让你可以同时管理多个 Ziti 网络：

# Pre-configure two profiles
ziti-mcp-server init --auth-mode updb --profile prod ...
ziti-mcp-server init --auth-mode updb --profile staging ...

# Start with a specific profile active
ziti-mcp-server run --profile prod

在运行时，AI Agent 可以：

• 使用 loginUpdb、loginIdentity 等工具登录其他网络
• 使用 listNetworks 列出所有网络
• 使用 selectNetwork 切换网络
• 使用 logout 从网络注销

凭据存储在 ~/.config/ziti-mcp-server/config.json 中，权限为 0600。

会话管理

如需查看当前身份验证会话的信息：

ziti-mcp-server session
ziti-mcp-server session --profile prod

注销

ziti-mcp-server logout
ziti-mcp-server logout --profile prod

或者在运行时通过 AI Agent 使用 logout 工具注销。

🛠️ 支持的 MCP 工具

Ziti MCP Server 提供 201 个 Ziti API 工具以及 8 个元工具，可通过自然语言管理你的 Ziti 网络。工具按资源类型分类。

提示： 使用 --read-only 或 --tools 模式，仅开放你需要的工具。请参阅限制工具访问。

元工具（网络管理）

无论是否使用 --tools 或 --read-only 进行筛选，这些工具始终可用。

工具	描述
loginUpdb	使用用户名／密码身份验证进行连接
loginIdentity	使用 Ziti 身份 JSON（mTLS 证书）进行连接
loginClientCredentials	使用 OAuth2 客户端凭据进行连接
loginDeviceAuth	启动 OAuth2 设备身份验证流程（返回验证 URL）
completeLogin	浏览器批准后，完成待处理的设备身份验证登录
logout	断开与 Ziti 网络的连接（清除配置文件凭据）
listNetworks	列出所有已配置的网络配置文件及其连接状态
selectNetwork	切换当前活动的网络配置文件

工具类别

类别	工具	描述
身份	22	CRUD、关系、生命周期、姿态、追踪
服务	12	CRUD 和关系查询
边缘路由器	11	CRUD、关系、重新注册
边缘路由器策略	7	CRUD 和关系查询
服务边缘路由器策略	7	CRUD 和关系查询
服务策略	8	CRUD 和关系（拨号／绑定）
配置	6	CRUD 和服务关系
配置类型	6	CRUD 和配置查询
身份验证策略	5	CRUD（主要／次要身份验证设置）
身份验证器	5	CRUD（updb／证书）
证书颁发机构	7	CRUD、JWT 获取、验证
外部 JWT 签名者	5	外部 JWT 签名者的 CRUD
姿态检查	8	CRUD、类型和角色属性
路由器	5	Fabric 路由器的 CRUD
中转路由器	5	中转路由器的 CRUD
终结器	5	终结器的 CRUD
注册	5	CRUD 和刷新
控制器设置	6	CRUD 和有效值查询
控制器与系统信息	4	版本、功能、摘要
会话与 API 会话	6	列表、详情、删除
身份类型	2	列表和详情
Fabric（路由器、服务等）	34	Fabric 层 CRUD、电路、链路、集群、数据库快照

完整工具参考、详细表格和提示词示例，请参阅 docs/tools.md。

示例提示词

• Show me all Ziti identities
• Which identities have access to the Demo1 service?
• Create a new identity called 'demo-admin' and make it an admin
• List all edge routers and their status
• Show me all Dial service policies
• What version is the Ziti controller running?
• Give me a summary of the network — how many identities, services, and routers exist?
• Create a Bind policy for the 'my-api' service

🔒 安全

限制工具访问

配置 Ziti MCP Server 时，请根据具体需求限制工具访问：

# Enable only read-only operations
ziti-mcp-server run --read-only

# Alternative way to enable only read-only operations
ziti-mcp-server run --tools 'list*,get*'

# Limit to just identity-related tools
ziti-mcp-server run --tools '*Identit*'

# Limit to read-only identity-related tools
ziti-mcp-server run --tools '*Identit*' --read-only

# Run the server with all tools enabled
ziti-mcp-server run --tools '*'

重要

同时使用 --read-only 和 --tools 标志时，出于安全考虑，--read-only 标志优先级更高。无论筛选设置如何，元工具（login、logout、listNetworks、selectNetwork）始终可用。

这种做法有以下几项重要优势：

1. 增强安全性：限制可用工具可缩小潜在攻击面。
2. 提升性能：工具越少，工具推理所需的上下文窗口占用就越少。
3. 基于资源的访问控制：使用不同的工具集配置不同实例。
4. 简化审计：更容易跟踪执行过的操作。

凭据存储

• 凭据存储在 ~/.config/ziti-mcp-server/config.json 中，权限为 0600
• 配置文件不会对所有用户开放读取权限
• 身份验证支持 OAuth 2.0 设备授权、客户端凭据、mTLS 证书和 UPDB
• 可通过 logout 命令或工具轻松移除凭据

重要

为遵循安全最佳实践，请在会话结束或切换网络时始终退出登录。

注意

请务必检查身份验证过程中请求的权限，确保其符合您的安全要求。

安全扫描

我们建议定期使用社区开发的工具扫描此服务，以发现协议层面的风险：

• mcpscan.ai — 用于 MCP 端点的 Web 扫描工具
• mcp-scan — 用于评估服务行为的 CLI 工具

问题反馈

如需提供反馈或报告 bug，请在我们的问题跟踪器中提交 issue。

🩺 故障排除

首先查看所有可用命令和选项，开始排查问题：

ziti-mcp-server help

🚨 常见问题

1. 身份验证失败

   • 确保你在 Ziti 网络中拥有正确的权限
   • 尝试使用 ziti-mcp-server init --auth-mode <mode> ... 重新初始化
   • 或使用运行时登录工具重新进行身份验证

2. TLS 证书错误

   • 登录时，服务会通过 EST /cacerts 端点自动获取控制器的 CA
   • 如果获取 CA 失败，请将控制器 CA 添加到系统信任存储区
   • 或重新登录以触发新一轮 CA 获取

3. 客户端无法连接到服务

   • 配置更改后，重启 MCP 客户端
   • 检查客户端配置中的二进制文件路径是否正确

4. 配置无效错误

   • 通常是因为没有激活的配置文件或缺少凭据
   • 使用 listNetworks 检查配置文件状态
   • 使用登录工具或 ziti-mcp-server init 进行身份验证

提示

重启服务和 MCP 客户端通常可以解决大多数连接问题。

📋 调试日志

启用调试模式以查看详细日志：

export OPENZITI_MCP_DEBUG=true

查看 Claude Desktop 中详细的 MCP 客户端日志：

# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

👨‍💻 开发

从源代码构建

# Clone the repository
git clone https://github.com/openziti/ziti-mcp-server.git
cd ziti-mcp-server-go

# Build
go build ./cmd/ziti-mcp-server

# Run
./ziti-mcp-server run

重新生成 API 客户端

internal/gen/ 中的 Ziti API 客户端由 OpenAPI 规范通过 go-swagger 生成：

make generate