MCP Ziti

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.

______________________________________________________________________

工具

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

______________________________________________________________________

先决条件

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

______________________________________________________________________

安装

下载版本

macOS、Linux和Windows的预构建二进制文件可在 .

1. 从以下网址下载适用于您平台的存档 最新版本.
2. 提取 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文件： ``bash # 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）.

1. 代理人打电话来 start-oidc-login 具有控制器URL、OIDC颁发者和客户端ID
2. 该工具返回一个验证URL和一个用户代码——代理将两者都呈现给用户
3. 用户在浏览器中打开URL，输入代码，并使用IdP进行身份验证
4. 代理人打电话来 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要求反斜杠转义为 \\.在所有文件路径中使用双反斜杠： ``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"
      ]
    }
  }
}

______________________________________________________________________

标志参考

______________________________________________________________________

建造和测试

构建

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 ./...