使用说明

mcp-ziti

一 MCP（模型上下文协议）暴露的服务器 OpenZiti 的管理人工智能代理的API。它允许任何兼容MCP的客户端——Claude Desktop、Cursor、VS Code Copilot等——使用自然语言创建、检查和管理OpenZiti网络中的资源。

服务器通过STDIO进行通信。它可以在启动时使用五种方法之一（身份JSON文件、用户名/密码、客户端证书、外部JWT令牌或OIDC客户端凭据）与OpenZiti控制器进行身份验证，也可以启动 没有任何凭据 并让AI代理在运行时通过 connect-controller 工具。对于通过浏览器进行交互式OIDC登录（OAuth 2.0设备授权授予），代理可以使用 start-oidc-login 和 complete-oidc-login.

工具

类别	工具	描述
连接	`connect-controller`	运行时连接（或重新连接）到Ziti控制器
	`disconnect-controller`	断开与当前控制器的连接并清除凭据
	`get-controller-status`	获取当前连接状态和控制器URL
	`start-oidc-login`	通过浏览器启动交互式OIDC登录（设备授权授予）
	`complete-oidc-login`	完成OIDC设备登录并连接到控制器
身份	`list-identities`	使用可选筛选器和分页列出标识
	`get-identity`	通过ID获取单个身份
	`create-identity`	创建新标识（设备、用户、路由器或服务）
	`update-identity`	重命名、更改类型、切换管理员标志或更新角色属性
	`delete-identity`	永久删除身份
服务	`list-services`	列出具有可选筛选器和分页的服务
	`get-service`	按ID获取单个服务
	`create-service`	创建新服务
	`update-service`	更新服务的名称、加密设置或角色属性
	`delete-service`	永久删除服务
服务政策	`list-service-policies`	列出服务策略
	`get-service-policy`	按ID获取单个服务策略
	`create-service-policy`	创建拨号或绑定服务策略
	`update-service-policy`	更新服务策略
	`delete-service-policy`	永久删除服务策略
边缘路由器策略	`list-edge-router-policies`	列出边缘路由器策略
	`get-edge-router-policy`	按ID获取单边缘路由器策略
	`create-edge-router-policy`	创建边缘路由器策略
	`delete-edge-router-policy`	永久删除边缘路由器策略
服务边缘路由器策略	`list-service-edge-router-policies`	列出服务边缘路由器策略
	`get-service-edge-router-policy`	按ID获取单服务边缘路由器策略
	`create-service-edge-router-policy`	创建服务边缘路由器策略
	`update-service-edge-router-policy`	更新服务边缘路由器策略
	`delete-service-edge-router-policy`	永久删除服务边缘路由器策略
边界路由器	`list-edge-routers`	列出边缘路由器
	`get-edge-router`	按ID获取单边路由器
路由器	`list-routers`	列出结构路由器（边缘和非边缘）
	`get-router`	按ID获取单个结构路由器
认证装置	`list-authenticators`	列出身份验证器（附加到身份的凭据）
	`get-authenticator`	按ID获取单个身份验证器
	`update-authenticator`	更新updb身份验证器的用户名/密码
	`delete-authenticator`	永久删除身份验证器
注册人数	`list-enrollments`	列出待定的注册
	`get-enrollment`	按ID获取单个注册
	`create-enrollment`	创建新注册（ott、ottca或updb）
	`delete-enrollment`	删除待处理的注册
证书颁发机构	`list-certificate-authorities`	列出CA
	`get-certificate-authority`	按ID获取单个CA
	`create-certificate-authority`	创建新CA
	`update-certificate-authority`	更新CA
	`delete-certificate-authority`	永久删除CA
外部JWT签名者	`list-external-jwt-signers`	列出外部JWT签名者
	`get-external-jwt-signer`	按ID获取单个外部JWT签名者
	`create-external-jwt-signer`	创建外部JWT签名者（证书或JWKS）
	`update-external-jwt-signer`	更新外部JWT签名者
	`delete-external-jwt-signer`	永久删除外部JWT签名者
身份验证策略	`list-auth-policies`	列出身份验证策略
	`get-auth-policy`	按ID获取单个身份验证策略
	`create-auth-policy`	创建身份验证策略
	`update-auth-policy`	更新身份验证策略
	`delete-auth-policy`	永久删除身份验证策略
配置	`list-config-types`	列出服务配置类型
	`get-config-type`	按ID获取单个配置类型
	`create-config-type`	创建新的配置类型
	`delete-config-type`	永久删除配置类型
	`list-configs`	列出服务配置
	`get-config`	按ID获取单个配置
	`create-config`	创建新的服务配置
	`update-config`	更新服务配置
	`delete-config`	永久删除服务配置
姿势检查	`list-posture-checks`	列出姿势检查
	`get-posture-check`	通过ID进行单一姿势检查
	`list-posture-check-types`	列出可用的姿势检查类型
	`delete-posture-check`	永久删除姿势检查
端子	`list-terminators`	列表终止符
	`get-terminator`	按ID获取单个终止符
	`create-terminator`	创建一个将服务链接到路由器地址的终止符
	`delete-terminator`	永久删除终止符
会话	`list-api-sessions`	列出活动管理API会话
	`get-api-session`	通过ID获取单个API会话
	`delete-api-session`	强制删除API会话
	`list-sessions`	列出活动网络（数据平面）会话
	`get-session`	按ID获取单个网络会话
	`delete-session`	终止网络会话
角色属性	`list-identity-role-attributes`	列出身份上使用的角色属性
	`list-edge-router-role-attributes`	列出边缘路由器上正在使用的角色属性
	`list-service-role-attributes`	列出服务上正在使用的角色属性
	`list-posture-check-role-attributes`	列出姿势检查中使用的角色属性
网络	`get-controller-version`	获取控制器版本和构建信息
	`list-summary`	获取整个网络的资源计数摘要
	`list-controllers`	列出HA群集中的控制器
数据库	`create-database-snapshot`	触发即时数据库备份快照
	`check-data-integrity`	对控制器数据库运行完整性检查
	`fix-data-integrity`	尝试自动修复数据完整性问题

列表工具接受 filter, limit （默认值为100，最大值为500），以及 offset 用于过滤和分页的参数。

先决条件

一 OpenZiti 的可从运行MCP服务器的计算机访问的控制器

安装

下载版本

macOS、Linux和Windows的预构建二进制文件可在 GitHub发布页面.

从以下网址下载适用于您平台的存档最新版本.
提取 ziti-mcp 二进制文件，并将其放置在PATH中的某个位置（例如。 /usr/local/bin).

# Example: macOS Apple Silicon
ZMCP_VER="$(curl -sL https://api.github.com/repos/smilindave26/mcp-ziti/releases/latest | sed -n '/tag_name/s/.*v\([0-9]*\.[0-9]*\.[0-9]*\).*/\1/p')"
curl -sL "https://github.com/smilindave26/mcp-ziti/releases/download/v${ZMCP_VER}/mcp-ziti_${ZMCP_VER}_darwin_arm64.tar.gz" | tar xz ziti-mcp
sudo mv ziti-mcp /usr/local/bin/

滚动 开发版本 预发布来自的最新二进制文件 main 也可用于测试。

来源

需要Go 1.24或更高版本。

git clone https://github.com/smilindave26/mcp-ziti.git
cd mcp-ziti
go build -o ziti-mcp .

结果 ziti-mcp 二进制文件是一个独立的可执行文件，没有运行时依赖关系。

认证

凭据是 启动时可选如果未配置身份验证，服务器将在断开连接的状态下启动，AI代理稍后可以使用 connect-controller 工具。提供凭据时，必须使用一种身份验证方法。所有选项都可以作为CLI标志或环境变量使用（标志优先）。

身份JSON文件

Ziti身份文件在单个JSON文件中包含控制器URL、客户端证书和CA包。当您已经注册了身份时，这是最简单的选择。

如何获取身份文件： 在你的 OpenZiti 的网络，创建一个身份并下载其一次性注册JWT，然后使用 ziti CLI生成JSON文件：
# Create an identity via the CLI or web console, then enroll with the JWT
ziti edge enroll --jwt /path/to/identity.jwt --out /path/to/identity.json
结果 identity.json 这就是你所传递的 --identity-file。请参阅 OpenZiti报名文件有关详细信息，包括通过 CloudZiti控制台或管理API。

# The controller URL is read from the ztAPI field inside the file
ziti-mcp --identity-file /path/to/identity.json

# Override the controller URL if needed
ziti-mcp --identity-file /path/to/identity.json \
          --controller https://ctrl.example.com:1280

环境变量：

ZITI_IDENTITY_FILE=/path/to/identity.json ziti-mcp

用户名/密码

使用控制器的内置用户数据库（updb）进行身份验证。需要 --controller.

ziti-mcp --controller https://ctrl.example.com:1280 \
          --username admin \
          --password secret

环境变量：

ZITI_CONTROLLER_URL=https://ctrl.example.com:1280 \
ZITI_USERNAME=admin \
ZITI_PASSWORD=secret \
ziti-mcp

客户端证书

使用TLS客户端证书和私钥进行身份验证。需要 --controller.

ziti-mcp --controller https://ctrl.example.com:1280 \
          --cert /path/to/client.crt \
          --key  /path/to/client.key

环境变量：

ZITI_CONTROLLER_URL=https://ctrl.example.com:1280 \
ZITI_CERT_FILE=/path/to/client.crt \
ZITI_KEY_FILE=/path/to/client.key \
ziti-mcp

外部JWT（静态令牌）

使用预先颁发的JWT进行身份验证，例如IdP中的服务帐户令牌或控制器颁发的长期API令牌。需要 --controller.

直接以字符串形式提供令牌：

ziti-mcp --controller https://ctrl.example.com:1280 \
          --ext-jwt-token eyJhbGciOiJSUzI1NiJ9...

或者指向包含令牌的文件（对于Kubernetes挂载的secrets很有用）：

ziti-mcp --controller https://ctrl.example.com:1280 \
          --ext-jwt-file /var/run/secrets/token.jwt

环境变量：

ZITI_CONTROLLER_URL=https://ctrl.example.com:1280 \
ZITI_EXT_JWT_TOKEN=eyJhbGciOiJSUzI1NiJ9... \
ziti-mcp

OIDC客户端凭据

使用身份验证 OAuth 2.0客户端凭据流。在每个会话上从IdP中获取一个新的令牌，因此不需要手动轮换令牌。需要 --controller 和 --oidc-issuer.

ziti-mcp --controller https://ctrl.example.com:1280 \
          --oidc-issuer https://idp.example.com \
          --oidc-client-id my-client \
          --oidc-client-secret my-secret

可选附加功能：

# Restrict the token audience
ziti-mcp ... --oidc-audience https://ctrl.example.com

# Skip OIDC discovery and use a known token endpoint directly
ziti-mcp ... --oidc-token-url https://idp.example.com/oauth/token

环境变量：

ZITI_CONTROLLER_URL=https://ctrl.example.com:1280 \
ZITI_OIDC_ISSUER=https://idp.example.com \
ZITI_OIDC_CLIENT_ID=my-client \
ZITI_OIDC_CLIENT_SECRET=my-secret \
ziti-mcp

交互式OIDC登录（浏览器）

对于通过第三方IdP配置的没有客户端密码的用户，AI代理可以使用 OAuth 2.0设备授权授予（RFC 8628）.

代理人打电话来 start-oidc-login 具有控制器URL、OIDC颁发者和客户端ID
该工具返回一个验证URL和一个用户代码——代理将两者都呈现给用户
用户在浏览器中打开URL，输入代码，并使用IdP进行身份验证
代理人打电话来 complete-oidc-login 它轮询IdP直到身份验证完成，然后连接

在启动时预先配置连接详细信息，这样代理就不需要每次都提供它们——省略 --oidc-client-secret 在OIDC默认设置就绪的断开连接模式下启动：

ziti-mcp --controller https://ctrl.example.com:1280 \
          --oidc-issuer https://idp.example.com \
          --oidc-client-id my-public-client

或者在MCP服务器配置中：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp",
      "args": [
        "--controller", "https://ctrl.example.com:1280",
        "--oidc-issuer", "https://idp.example.com",
        "--oidc-client-id", "my-public-client"
      ]
    }
  }
}

然后，代理人可以简单地拨打电话 start-oidc-login 没有参数，所有连接细节都从启动配置中填写。

这需要IdP支持设备授权授予流（Auth0、Okta和Keycloak都支持）。

可选CA覆盖

默认情况下，服务器从其众所周知的端点获取控制器的CA包。若要改用自定义CA，请添加 --ca （或 ZITI_CA_FILE)上述任何一种方法：

ziti-mcp --controller https://ctrl.example.com:1280 \
          --username admin --password secret \
          --ca /path/to/ca-bundle.pem

代理配置

服务器通过STDIO进行通信。通过指向二进制文件并传递首选身份验证标志，在代理的设置中将其配置为MCP服务器。

Windows用户： JSON要求反斜杠转义为 \\.在所有文件路径中使用双反斜杠：
{
  "mcpServers": {
    "ziti": {
      "command": "C:\\Users\\you\\ziti-mcp.exe",
      "args": ["--identity-file", "C:\\Users\\you\\.ziti\\identity.json"]
    }
  }
}

您还可以启动服务器 完全没有凭据 --然后，代理可以在运行时使用 connect-controller 工具：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp"
    }
  }
}

克劳德桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

身份文件：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp",
      "args": ["--identity-file", "/path/to/identity.json"]
    }
  }
}

用户名/密码：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp",
      "args": [
        "--controller", "https://ctrl.example.com:1280",
        "--username", "admin",
        "--password", "secret"
      ]
    }
  }
}

客户端证书：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp",
      "args": [
        "--controller", "https://ctrl.example.com:1280",
        "--cert", "/path/to/client.crt",
        "--key",  "/path/to/client.key"
      ]
    }
  }
}

使用环境变量 （将凭据排除在配置文件之外）：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp",
      "env": {
        "ZITI_CONTROLLER_URL": "https://ctrl.example.com:1280",
        "ZITI_USERNAME": "admin",
        "ZITI_PASSWORD": "secret"
      }
    }
  }
}

光标

编辑 .cursor/mcp.json 在项目根目录中，或 ~/.cursor/mcp.json 对于全局配置：

身份文件：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp",
      "args": ["--identity-file", "/path/to/identity.json"]
    }
  }
}

用户名/密码：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp",
      "args": [
        "--controller", "https://ctrl.example.com:1280",
        "--username", "admin",
        "--password", "secret"
      ]
    }
  }
}

客户端证书：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp",
      "args": [
        "--controller", "https://ctrl.example.com:1280",
        "--cert", "/path/to/client.crt",
        "--key",  "/path/to/client.key"
      ]
    }
  }
}

VS代码（GitHub副本）

添加到您的 .vscode/mcp.json 或用户 settings.json 在...之下 "mcp":

身份文件：

{
  "servers": {
    "ziti": {
      "type": "stdio",
      "command": "/usr/local/bin/ziti-mcp",
      "args": ["--identity-file", "/path/to/identity.json"]
    }
  }
}

用户名/密码：

{
  "servers": {
    "ziti": {
      "type": "stdio",
      "command": "/usr/local/bin/ziti-mcp",
      "args": [
        "--controller", "https://ctrl.example.com:1280",
        "--username", "admin",
        "--password", "secret"
      ]
    }
  }
}

客户端证书：

{
  "servers": {
    "ziti": {
      "type": "stdio",
      "command": "/usr/local/bin/ziti-mcp",
      "args": [
        "--controller", "https://ctrl.example.com:1280",
        "--cert", "/path/to/client.crt",
        "--key",  "/path/to/client.key"
      ]
    }
  }
}

克劳德代码（CLI）

添加到您的项目 .claude/settings.json 或 ~/.claude/settings.json:

身份文件：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp",
      "args": ["--identity-file", "/path/to/identity.json"]
    }
  }
}

用户名/密码：

{
  "mcpServers": {
    "ziti": {
      "command": "/usr/local/bin/ziti-mcp",
      "args": [
        "--controller", "https://ctrl.example.com:1280",
        "--username", "admin",
        "--password", "secret"
      ]
    }
  }
}

标志参考

标志	环境变量	描述
`--controller`	`ZITI_CONTROLLER_URL`	控制器URL，例如。 `https://ctrl.example.com:1280`
`--identity-file`	`ZITI_IDENTITY_FILE`	Ziti身份JSON文件的路径
`--username`	`ZITI_USERNAME`	updb身份验证的用户名
`--password`	`ZITI_PASSWORD`	updb身份验证密码
`--cert`	`ZITI_CERT_FILE`	PEM客户端证书文件的路径
`--key`	`ZITI_KEY_FILE`	PEM私钥文件的路径
`--ca`	`ZITI_CA_FILE`	PEM CA包的路径（可选覆盖）
`--ext-jwt-token`	`ZITI_EXT_JWT_TOKEN`	外部JWT令牌字符串
`--ext-jwt-file`	`ZITI_EXT_JWT_FILE`	包含外部JWT的文件的路径
`--oidc-issuer`	`ZITI_OIDC_ISSUER`	OIDC发行人URL
`--oidc-client-id`	`ZITI_OIDC_CLIENT_ID`	OIDC客户端ID
`--oidc-client-secret`	`ZITI_OIDC_CLIENT_SECRET`	OIDC客户端密码（客户端凭据流需要，交互式登录省略）
`--oidc-audience`	`ZITI_OIDC_AUDIENCE`	OIDC受众声明（可选）
`--oidc-token-url`	`ZITI_OIDC_TOKEN_URL`	OIDC令牌端点URL--跳过发现（可选）

建造和测试

构建

go build ./...

# Build to an explicit output path
go build -o ziti-mcp .

单元测试

不需要外部依赖。

go test ./internal/...

集成测试

集成测试启动直播 OpenZiti 的网络使用 ziti edge quickstart 并对其运行所有23个工具。如果 ziti 二进制文件不在PATH中。

安装 ziti 二进制从 OpenZiti发布页面那么：

go test -v -timeout 5m ./test/integration/...

按名称运行单个测试：

go test -v -timeout 5m -run TestFullWorkflow ./test/integration/...

棉绒

golangci-lint run ./...

使用说明

mcp-ziti

工具

先决条件

安装

下载版本

来源

认证

身份JSON文件

用户名/密码

客户端证书

外部JWT（静态令牌）

OIDC客户端凭据

交互式OIDC登录（浏览器）

可选CA覆盖

代理配置

克劳德桌面版

光标

VS代码（GitHub副本）

克劳德代码（CLI）

标志参考

建造和测试

构建

单元测试

集成测试

棉绒

相关 MCP

Flomo笔记服务

网页抓取与搜索MCP服务器

用户名搜索MCP服务器

Jupyter笔记本MCP服务器

3D资产生成服务

文档搜索服务