Argo CD MCP Server

Argo CD MCP 服务

这是一个为 Argo CD 实现的 模型上下文协议（MCP） 服务，可让 AI 助手通过自然语言与您的 Argo CD 应用交互。该服务通过 stdio 和 HTTP 流传输协议，可与 Visual Studio Code 及其他 MCP 客户端无缝集成。

---

功能

• 传输协议：同时支持 stdio 和 HTTP 流传输模式，可灵活集成不同客户端
• 完整的 Argo CD API 集成：全面访问 Argo CD 资源和操作
• 适用于 AI 助手：预配置工具，让 AI 助手可以通过自然语言与 Argo CD 交互

可用工具

该服务提供以下 ArgoCD 管理工具：

集群管理

• list_clusters：列出在 ArgoCD 中注册的所有集群

项目管理

• get_appproject：获取特定 AppProject（项目）的详细信息

应用管理

• list_applications：列出并筛选所有应用
• get_application：获取特定应用的详细信息
• get_application_events：获取特定应用的事件
• create_application：创建新应用
• update_application：更新现有应用
• delete_application：删除应用
• sync_application：触发应用同步操作

资源管理

• get_application_resource_tree：获取特定应用的资源树
• get_application_managed_resources：获取特定应用的受管资源
• get_resources：获取应用所管理资源的清单
• get_application_workload_logs：获取应用工作负载（Pod、Deployment 等）的日志
• get_resource_events：获取应用所管理资源的事件
• get_resource_actions：获取资源可用的操作
• run_resource_action：对资源执行操作

安装

前提条件

• Node.js（建议 v18 或更高版本）
• pnpm 包管理器（用于开发）
• 可通过 API 访问的 Argo CD 实例
• Argo CD API 令牌（参见说明文档）

在 Cursor 中使用

1. 按照 Cursor 的 MCP 支持文档操作，并在项目中创建 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

2. 启动 Agent 模式对话即可使用 MCP。

在 VSCode 中使用

1. 按照在 VS Code 中使用 MCP 服务的文档，并在项目中创建 .vscode/mcp.json 文件：

{
  "servers": {
    "argocd-mcp-stdio": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

2. 在 VS Code 中与支持 MCP 的 AI 助手开始对话。

在 Claude Desktop 中使用

1. 按照 Claude Desktop 中的 MCP 文档，并创建 claude_desktop_config.json 配置文件：

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

2. 在设置中配置 Claude Desktop 使用此配置文件。

自签名证书

如果你的 Argo CD 实例使用自签名证书或来自私有证书颁发机构（CA）的证书，你可能需要在配置中添加以下环境变量：

"NODE_TLS_REJECT_UNAUTHORIZED": "0"

这会在 Node.js 连接使用自签名证书或来自系统证书存储中不受信任的私有 CA 的证书的 Argo CD 实例时，禁用 TLS 证书验证。

警告：禁用 SSL 验证会降低安全性。仅在开发环境中使用此设置，或在了解其安全影响后再使用。

提供 ArgoCD 凭据

服务使用基础 URL和 API 令牌连接到 ArgoCD。

API 令牌 — 仅限请求头／环境变量（必需）

ArgoCD 的 API 令牌是机密信息，只会从传输层读取，绝不会从工具调用参数中读取：

• HTTP 请求头（仅限 HTTP 传输）：x-argocd-api-token。
• 环境变量：ARGOCD_API_TOKEN（所有传输方式）。

此令牌仅用于出站：它用于对该服务进行身份验证，使其能够连接 ArgoCD，绝不会授权入站调用方。请参阅网络暴露，了解哪些对象可以访问监听器。

这是默认令牌。除非配置了令牌注册表，否则必须提供此令牌：对于 HTTP 传输，如果连接未提供令牌（请求头和环境变量均未设置），则会被拒绝并返回 400 Bad Request；但配置注册表后，允许不带令牌的连接，因为每次调用都会解析自己的注册表令牌。将令牌排除在工具参数之外，可确保它不会进入提示词、模型上下文或工具调用日志。

基础 URL — 请求头／环境变量，或每次调用的参数

基础 URL 可以在会话级别提供（服务启动时或 HTTP 客户端连接时解析一次）：

• HTTP 请求头（仅限 HTTP 传输）：x-argocd-base-url。
• 环境变量：ARGOCD_BASE_URL（所有传输方式）。

此外，每个工具都接受可选的 argocdBaseUrl 参数：

• 如果存在会话默认基础 URL，argocdBaseUrl 为可选参数，并会覆盖该次调用的默认值。
• 如果未配置会话默认基础 URL（请求头和环境变量均未设置），则必须提供 argocdBaseUrl；不提供此参数的调用会返回错误。

Token 注册表 — 按基础 URL 配置 Token（多实例）

若要为多个 ArgoCD 实例分别使用各自的 Token，请配置 Token 注册表。由于 Token 属于机密信息，注册表会从 JSON 文件读取，而不是从环境变量读取——将 ARGOCD_TOKEN_REGISTRY_PATH 指向该文件（例如，挂载的 Kubernetes Secret）。这样可以避免 Token 出现在进程环境、崩溃转储和子进程继承的环境中。

ARGOCD_TOKEN_REGISTRY_PATH=/app/argocd-mcp/token-registry.json

该文件包含一个 JSON 数组，将基础 URL 映射到对应使用的 Token：

[
  { "baseUrl": "https://argo-a.example.com", "token": "<token-a>" },
  { "baseUrl": "https://argo-b.example.com", "token": "<token-b>" }
]

保护文件安全。 将文件访问权限限制为仅服务器用户可访问（例如，使用 chmod 400），并优先使用机密管理机制（Kubernetes Secret 卷、Vault agent 等），而不是将明文文件保存在磁盘上。

本地开发。 默认情况下，make run / make dev 目标运行时不会使用注册表；传入 ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json 即可使用注册表。请勿将文件放在 dist/ 下——每次构建时，tsup 都会以 clean: true 清空该目录。请参阅本地运行。

配置注册表后，调用方只需传入（非机密的）argocdBaseUrl 参数即可指定目标实例；服务器会将其与已注册的 Token 配对。Token 不会出现在工具调用负载中。

两种 Token

服务器使用两种不同的 Token 处理调用。明确区分它们是安全模型得以成立的关键：

	默认 Token	注册表 Token
来源	x-argocd-api-token 请求头 / ARGOCD_API_TOKEN 环境变量（会话凭据）	ARGOCD_TOKEN_REGISTRY_PATH JSON 文件中按 baseUrl 索引的 token 条目
作用范围	仅限默认基础 URL（x-argocd-base-url / ARGOCD_BASE_URL）	仅限其条目所绑定的特定基础 URL
用途	目标为默认基础 URL 的调用	目标为注册表中任意基础 URL 的调用（包括将默认基础 URL 作为回退）
绝不会用于	默认基础 URL 以外的任何基础 URL——它绝不会发送到其他主机	未注册的任何基础 URL

最重要的规则：**默认 Token 绑定到默认基础 URL；其他所有主机的 Token 都必须来自注册表。**注册表 Token 仅绑定到注册时对应的主机。

解析顺序

对于给定的调用，解析出的基础 URL 为 argocdBaseUrl 参数（如果已提供），否则为会话默认值。随后按以下规则选择令牌：

1. 调用指向默认基础 URL → 使用默认令牌。如果未提供默认令牌（无令牌会话），则回退使用该基础 URL 对应的注册表令牌（如果存在）。
2. 调用指向其他基础 URL → 仅使用该基础 URL 对应的注册表令牌。这里绝不会使用默认令牌——不会将其发送到默认主机以外的主机。
3. 如果以上情况都不适用（无法为请求的基础 URL 解析出令牌），调用将返回 "Missing required ArgoCD API token" 错误，并且不会向该主机发送请求。

为什么默认令牌绑定到默认基础 URL。 argocdBaseUrl 参数来自工具调用，因此调用方（或被提示词注入的模型）可能会将其指向任意主机。如果默认令牌与任何提供的基础 URL 配对，该令牌就会作为 Authorization: Bearer 标头发送到攻击者的主机。将默认令牌限制为仅用于默认基础 URL，并要求为其他每台主机显式添加注册表条目，可防止令牌外泄。要连接其他实例，必须预先注册其令牌（以及相应的主机名）。

查找时会对基础 URL 进行规范化处理（主机名转为小写，忽略末尾斜杠），因此细微的格式差异仍可匹配。配置注册表后，HTTP 传输不再要求在连接时提供 x-argocd-api-token——由于每次调用的基础 URL 都会解析出对应令牌，因此允许无令牌连接。如果设置了 ARGOCD_TOKEN_REGISTRY_PATH，但文件缺失、无法读取或格式错误，服务会以失败关闭：启动时直接抛出错误，而不会静默回退到默认凭据，因此配置错误的注册表绝不会导致调用使用错误的令牌进行路由。

例如，tools/call 请求仅覆盖基础 URL：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_applications",
    "arguments": {
      "argocdBaseUrl": "https://argocd.other-cluster.example.com"
    }
  }
}

将基础 URL 覆盖为指向不同实例时，必须提供注册表令牌。 默认令牌（x-argocd-api-token / ARGOCD_API_TOKEN）仅绑定到默认基础 URL，绝不会发送到其他主机。将 argocdBaseUrl 覆盖为指向默认实例（主机相同，格式差异除外）时，会复用默认令牌；指向任何其他实例时，则必须提供该实例的注册表令牌，否则调用会因 "Missing required ArgoCD API token" 而失败，且不会发送请求。这是有意为之——请参阅上文为什么默认令牌绑定到默认基础 URL。

网络暴露

http 和 sse 传输会启动网络监听器，从而开放所有 ArgoCD 工具，包括 create_application、delete_application、sync_application 和 run_resource_action。默认情况下，它仅绑定到回环地址。

ARGOCD_API_TOKEN 不会保护它。 该令牌用于验证此服务向 ArgoCD 发起的请求。它与调用者的身份无关。入站访问由以下设置控制。

设置	标志	环境变量	默认值	作用
绑定地址	--bind-address	MCP_BIND_ADDRESS	127.0.0.1	监听器接受连接的地址。
入站令牌	—	MCP_AUTH_TOKEN	未设置	设置后，每个请求都必须携带 Authorization: Bearer <token>。
允许的 Host	--allowed-host-header	—	回环地址名称	额外允许出现在请求 Host 标头中的主机名。每个名称需单独指定一次。
允许的 Origin	--allowed-origin	—	回环源	额外允许出现在请求 Origin 标头中的浏览器源。每个源需单独指定一次。
外部身份验证	--allow-unauthenticated	—	false	当前置组件已对调用者进行身份验证时，允许在没有令牌的情况下绑定到非回环地址。
端口	--port	—	3000	监听的端口。

--bind-address 决定谁可以连接。--allowed-host-header 只检查已连接的客户端声称使用的主机名。两者并非一组配套设置，后者也不是防火墙。

没有对应环境变量的标志需要作为参数传入，容器中也一样：docker run <image> http --allow-unauthenticated。

行为：

• 扩大绑定范围时，必须设置 MCP_AUTH_TOKEN 或使用 --allow-unauthenticated。否则，服务会记录原因并以非零状态退出，而不会在暴露的状态下启动。
• 始终会检查 Origin 的协议、主机和端口。这可以阻止恶意网页，包括使用 DNS 重绑定的网页。
• 在回环绑定时，或在任何绑定配置下至少指定一个 --allowed-host-header 时，都会检查 Host。否则，由于无法确定客户端合法使用的主机名，检查会跳过并记录警告。
• GET /healthz 不受此限制，因此 kubelet 探针仍可成功。该端点仅返回存活状态。
• 配置不可用时，服务会在启动时说明原因并失败，而不会忽略配置。
• 只读模式与上述设置相互独立，并会限制任何调用者可执行的操作。

有意暴露监听器：

export MCP_AUTH_TOKEN=<inbound_token>
node dist/index.js http --bind-address 0.0.0.0 --allowed-host-header mcp.internal.example.com

容器镜像同样默认绑定到回环地址，因此当调用者与其共享网络命名空间时（例如位于同一 Kubernetes Pod 中的 sidecar），无需额外配置：

docker run -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  argoprojlabs/mcp-for-argocd

要发布端口，请扩大绑定范围并设置入站凭据：

docker run -p 3000:3000 \
  -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  -e MCP_BIND_ADDRESS=0.0.0.0 -e MCP_AUTH_TOKEN=<inbound_token> \
  argoprojlabs/mcp-for-argocd

当绑定范围已扩大，且代理或网格已对调用者进行身份验证时，请使用 --allow-unauthenticated，而不是 MCP_AUTH_TOKEN。

部署注意事项请参阅运维说明。

只读模式

如果你想以只读模式运行 MCP 服务，以避免修改资源或应用，应设置环境变量：

"MCP_READ_ONLY": "true"

这会禁用以下工具：

• create_application
• update_application
• delete_application
• sync_application
• run_resource_action

默认情况下，所有工具均可用。

无状态模式

默认情况下，HTTP 传输会为每个客户端连接分配一个会话 ID，并在内存中保存活动会话映射。对于单实例部署，这种方式运行良好；但在未启用会话粘性的情况下运行多个副本时，会导致 400 错误，因为请求被路由到其他 Pod 后，将无法找到在原 Pod 上创建的会话。

若要在无需会话亲和性的情况下运行，请使用 --stateless 标志启动服务：

node dist/index.js http --stateless

或使用 Docker：

docker run -p 3000:3000 \
  -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  -e MCP_BIND_ADDRESS=0.0.0.0 -e MCP_AUTH_TOKEN=<inbound_token> \
  argoprojlabs/mcp-for-argocd http --stateless

该镜像设置了 ENTRYPOINT，因此覆盖命令只会替换参数。需要发布端口，才能使用更宽泛的绑定地址并使此处的入站令牌成为必需项；请参阅网络暴露。

在无状态模式下：

• 不会返回或要求提供 Mcp-Session-Id — 任意副本都可以处理任意请求
• 每个请求都必须通过环境变量或 x-argocd-base-url / x-argocd-api-token 标头提供 ArgoCD 凭据（也可通过工具参数 argocdBaseUrl 按调用覆盖基础 URL；API 令牌只能通过标头或环境变量提供）
• GET /mcp 和 DELETE /mcp 会返回 405 Method Not Allowed（不支持会话级 SSE 和终止操作）

在无法使用网络层会话粘性的 Kubernetes 部署中，尤其是启用了水平 Pod 自动扩缩（HPA）的部署，建议使用此模式。

开发

1. 克隆仓库：

git clone https://github.com/argoproj-labs/mcp-for-argocd.git
cd mcp-for-argocd

2. 安装项目依赖：

pnpm install

3. 启动启用了热重载的开发服务：

pnpm run dev

服务启动后，你可以在 Visual Studio Code 或其他 MCP 客户端中使用 MCP 服务。

本地运行

Makefile 提供了通过 HTTP 传输运行服务的目标：

make run    # build, then run the HTTP server (production-style)
make dev    # run from source with hot reloading (tsx watch)

默认情况下，两个目标都不会设置任何凭据——服务启动时没有默认基础 URL 或令牌，因此调用方必须在每次请求中提供这些信息（通过 x-argocd-base-url / x-argocd-api-token 标头，或者在配置注册表后使用 argocdBaseUrl 工具参数）。端口也可以用相同方式覆盖：

make run PORT=4000

要配置凭据，请在命令行中导出相关环境变量。共有三个变量（均为可选）：

变量	用途
ARGOCD_BASE_URL	默认 ArgoCD 实例 URL；调用未覆盖该值时使用。
ARGOCD_API_TOKEN	默认基础 URL 对应的静态 API 令牌。
ARGOCD_TOKEN_REGISTRY_PATH	JSON 令牌注册表的路径，用于将基础 URL 映射到令牌（以指定多个实例）。

这些都是出站凭据。关于哪些人可以访问监听器，请参阅网络暴露。

# Single instance with a static base URL + token:
make run ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token>

# Multiple instances via a token registry:
make run ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json

# Both — a default instance plus extra instances resolved from the registry:
make dev ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token> \
  ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json

有关默认令牌与注册表如何交互，请参阅令牌解析。如果设置了 ARGOCD_TOKEN_REGISTRY_PATH，但文件不存在、不可读或格式错误，服务会在启动时采取故障关闭策略。

请勿让令牌出现在 shell 历史记录中。 直接在 make 命令行中传入 ARGOCD_API_TOKEN=<token> 会将密钥记录到 shell 历史记录中，并使其出现在进程列表里。建议先在 shell 中导出该变量，这样它就不会出现在 make 调用中：

export ARGOCD_API_TOKEN=<token>
make run ARGOCD_BASE_URL=https://argo.example.com

注册表路径（ARGOCD_TOKEN_REGISTRY_PATH）和基础 URL 不是密钥，可以直接传入。

请勿将注册表文件放在 dist/ 下——tsup 使用 clean: true 构建，每次构建都会清空该目录。

HTTP 服务监听 POST /mcp（默认地址为 127.0.0.1:3000；如需扩大访问范围，请参阅网络暴露），并提供 GET /healthz 存活检测端点。要发送请求，请先初始化（initialize）一个会话（记录响应标头中的 mcp-session-id），然后调用工具，并将已注册的基础 URL 之一作为 argocdBaseUrl 参数传入：

# 1. Initialize a session — note the mcp-session-id response header
curl -sD - http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# 2. Call a tool, reusing that session id
curl -s http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'mcp-session-id: <session-id-from-step-1>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_applications","arguments":{"argocdBaseUrl":"https://argo-a.example.com"}}}'

若要避免管理会话 ID，请以无状态模式运行（node dist/index.js http --stateless），这样每个 POST /mcp 请求都可独立完成。

升级 ArgoCD 类型定义

要根据最新的 Argo CD API 规范更新 TypeScript 类型定义：

1. 从 ArgoCD 发布页面下载 swagger.json 文件。例如，这是 ArgoCD v2.14.11 对应的 swagger.json 链接。

2. 将下载的 swagger.json 文件放在 argocd-mcp 项目的根目录中。

3. 运行以下命令，根据 Swagger 定义生成 TypeScript 类型。此操作会创建或覆盖 src/types/argocd.d.ts 文件：

   pnpm run generate-types
   

4. 更新 src/types/argocd-types.ts 文件，从新生成的 src/types/argocd.d.ts 中导出所需类型。此步骤通常需要人工检查，以确保只公开必要的类型。

致谢

该项目最初由 Akuity 的 @jiachengxu、@imwithye、@hwwn 和 @alexmt 创建并捐赠。