星战科技xingzhan.cloud
返回市场
argoCD-MCP

argoCD-MCP

作者：severity111 星标更新：2025-04-23
安装使用来源：spider==github.com

项目介绍

ArgoCD MCP 服务器

一个与 ArgoCD API 集成的 MCP（模型上下文协议）服务器，使AI助手和大型语言模型能够通过自然语言交互来管理 ArgoCD 应用程序和资源。

<a href="https://glama.ai/mcp/servers/@severity1/argocd-mcp"> <img width="380" height="200" src="https://gips1.baidu.com/it/u=2510378679,3068018273&fm=3081&app=3081&f=PNG?w=760&h=400" alt="argocd-mcp MCP 服务器" /> </a>

版本 Python 类型检查

特性

  • 身份验证及会话管理：
    • 从 ArgoCD API 获取用户信息
    • 基于令牌的身份验证
    • 访问服务器设置和配置
    • 获取插件信息
    • 获取版本信息
  • 应用程序管理：
    • 按项目、名称、命名空间列出并筛选应用程序
    • 获取详细的应用程序信息
    • 创建、更新和删除应用程序
    • 同步应用程序，可配置选项
  • 强大的API客户端：
    • URL规范化和智能端点处理
    • 全面的错误处理和详细的错误消息
    • 可配置的超时和SSL验证
    • 令牌安全保护和掩码
  • 开发者体验：
    • 使用 mypy 进行完整的静态类型检查
    • 详细的文档和示例
    • 基于环境的配置

快速开始

设置

# 克隆仓库
git clone https://github.com/severity1/argocd-mcp.git
cd argocd-mcp

# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate

# 安装依赖
uv pip install -e .

启动服务器

服务器通过环境变量进行配置。以下是可用的配置选项：

环境变量描述默认值
ARGOCD_TOKENArgoCD API 令牌无
ARGOCD_API_URLArgoCD API 端点https://argocd.example.com/api/v1
ARGOCD_VERIFY_SSL验证 SSL 证书true

你可以通过多种方式启动服务器：

# 使用 MCP 开发工具（提供调试工具）
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
mcp dev server.py

# 使用 MCP 运行命令
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
mcp run server.py

# 标准方法
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
uv run server.py

# 设置多个环境变量
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
export ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1
export ARGOCD_VERIFY_SSL=false  # 对自签名证书禁用 SSL 验证
uv run server.py

# 使用 .env 文件
echo "ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1
ARGOCD_VERIFY_SSL=false" > .env
uv run server.py

# 在后台运行
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
uv run server.py > server.log 2>&1 & echo $! > server.pid

当令牌通过环境变量提供时，Claude 可以在不需在每个命令中指定的情况下使用它。

与 Claude 连接

使用 Claude Code CLI

# 添加 MCP 服务器
claude mcp add argocd-mcp "uv run $(pwd)/server.py"

# 带有令牌
claude mcp add argocd-mcp -e ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN -- "uv run $(pwd)/server.py"

# 验证是否已添加
claude mcp list

# 为了调试，可以使用 MCP Inspector 和 'mcp dev' 命令

使用 Claude Desktop

创建一个 claude_desktop_config.json 配置文件：

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/argocd-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "ARGOCD_TOKEN": "your_argocd_token",
        "ARGOCD_API_URL": "https://your-argocd-server.com/api/v1",
        "ARGOCD_VERIFY_SSL": "true"
      }
    }
  }
}

替换路径和配置值为你实际的值：

  • 使用 uv 可执行文件的完整路径（在 macOS/Linux 上使用 which uv 或在 Windows 上使用 where uv 查找）
  • 设置正确的目录路径到你的 argocd-mcp 安装
  • 添加你的 ArgoCD API 令牌
  • 根据需要配置其他环境变量

此配置告诉 Claude Desktop 如何自动启动 MCP 服务器，并使用你的特定环境设置。

可用工具

会话工具

  • get_user_info: 通过 api/v1/session/userinfo 获取当前用户的资料

设置工具

  • get_settings: 获取 ArgoCD 服务器设置，包括 UI、OIDC 和其他配置
  • get_plugins: 获取有关配置的 ArgoCD 插件的信息

版本工具

  • get_version: 获取 API 服务器的版本信息

应用程序管理工具

  • list_applications: 获取所有应用程序，带有过滤选项
  • get_application_details: 获取特定应用程序的详细信息
  • create_application: 创建新的应用程序
  • update_application: 更新现有的应用程序
  • delete_application: 删除应用程序
  • sync_application: 触发应用程序的同步操作

示例对话

检查用户信息

用户：我在 ArgoCD 中的用户信息是什么？

Claude：让我检索您的用户信息。

⏺ argocd-mcp:get_user_info (MCP)
  ⎿  {"loggedIn": true, "username": "devops-user", "iss": "argocd"}

您登录的是 'devops-user'。

获取 ArgoCD 版本

用户：服务器上运行的 ArgoCD 是什么版本？

Claude：让我检查 ArgoCD 的版本信息。

 McCartney：argocd-mcp:get_version (MCP)
  ⎿  {
        "Version": "v2.9.3+5eaf684",
        "BuildDate": "2023-09-15T14:25:11Z",
        "GitCommit": "5eaf68452",
        "GitTreeState": "clean",
        "GoVersion": "go1.20.7",
        "Compiler": "gc",
        "Platform": "linux/amd64",
        "KustomizeVersion": "v5.1.1",
        "HelmVersion": "v3.12.3",
        "KubectlVersion": "v1.27.4",
        "JsonnetVersion": "v0.20.0"
      }

您正在运行 ArgoCD v2.9.3，构建于 2023 年 9 月 15 日。它运行在 Linux (amd64) 上，使用 Go 1.20.7，并包含 Kustomize v5.1.1 和 Helm v3.12.3。

获取 ArgoCD 设置

用户：显示我的 ArgoCD 服务器设置

Claude：让我为您检索 ArgoCD 服务器设置。

 McCartney：argocd-mcp:get_settings (MCP)
  ⎿  {
        "clusterSettings": {
          "appLabelKey": "argocd.argoproj.io/instance",
          "controllerNamespace": "argocd",
          "execEnabled": true,
          "statusBadgeEnabled": true,
          "uiBannerContent": "这是一个 ArgoCD 的开发实例",
          "url": "https://argocd.example.com"
        }
      }

这里是您 ArgoCD 服务器的关键设置：
- URL: https://argocd.example.com
- 控制器命名空间: argocd
- 执行启用: 是
- 状态徽章启用: 是
- UI 通告: "这是一个 ArgoCD 的开发实例"

管理应用程序

用户：我在“生产”项目中有哪些应用程序？

Claude：让我列出您在生产项目中的应用程序。

 McCartney：argocd-mcp:list_applications (MCP)
  ⎿  {
        "items": [
          {
            "metadata": {
              "name": "frontend-app",
            },
            "status": {
              "sync": {"status": "Synced"},
              "health": {"status": "Healthy"},
            }
          },
          {
            "metadata": {
              "name": "api-service",
            },
            "status": {
              "sync": {"status": "OutOfSync"},
              "health": {"status": "Healthy"},
            }
          },
          {
            "metadata": {
              "name": "database",
            },
            "status": {
              "sync": {"status": "Synced"},
              "health": {"status": "Degraded"},
            }
          }
        ]
      }

您在生产项目中有 3 个应用程序：
- frontend-app (同步，健康)
- api-service (不同步，健康)
- database (同步，降级)

用户：同步 api-service 应用程序

Claude：我将为您同步 api-service 应用程序。

 McCartney：argocd-mcp:sync_application (MCP)
  ⎿  {
        "resourcesResult": {
          "updated": ["Deployment/api-service"],
          "hooks": []
        },
        "status": "Syncing"
      }

应用程序同步已成功发起。同步操作现在正在进行中。

开发

要求

  • Python 3.12+
  • MCP（包括 FastMCP 和开发工具）
  • uv 包管理器（推荐）或 pip
  • ArgoCD API 令牌

类型检查

此项目使用 mypy 进行静态类型检查，以提高代码质量并尽早捕获与类型相关的错误：

# 安装 mypy
uv pip install mypy

# 运行类型检查
uv run -m mypy .

类型检查配置在 pyproject.toml 和 mypy.ini 中可用。该配置强制执行严格的类型规则，包括：

  • 禁止未定义类型
  • 返回 Any 类型时警告
  • 检查函数定义的完整性
  • 支持命名空间包
  • 模块特定的配置

项目结构

代码组织成模块化结构：

argocd-mcp/
├── api/              # API 客户端和通信
│   ├── __init__.py
│   └── client.py     # ArgoCD API 的 HTTP 客户端
├── models/           # 数据模型
│   ├── __init__.py
│   └── applications.py # 应用程序数据结构
├── tools/            # MCP 工具实现
│   ├── __init__.py
│   ├── session.py    # 会话工具（用户信息）
│   ├── applications.py # 应用程序管理工具
│   ├── settings.py   # 服务器设置工具
│   └── version.py    # 版本信息工具
├── utils/            # 实用函数
│   ├── __init__.py
├── server.py         # 主服务器入口点
├── pyproject.toml    # 项目配置和依赖项
└── mypy.ini          # Mypy 类型检查配置

扩展服务器

要添加新功能：

  1. 将新工具添加到 tools 目录下的适当模块中
  2. 在 server.py 中注册新工具
  3. 遵循现有模式进行参数验证和错误处理
  4. 更新 README.md 中的文档
  5. 为新功能添加测试

故障排除

如果遇到问题：

  1. 检查服务器日志（默认情况下已启用信息记录）
  2. 注意 Processing request of type CallToolRequest 是信息性的，不是错误
  3. 如果使用 mcp dev server.py，MCP Inspector 将自动在 http://localhost:5173 打开以供调试
  4. 使用服务器日志调试 API 调用和响应
  5. 对于自签名证书的 SSL 证书问题：
# 禁用 SSL 验证
export ARGOCD_VERIFY_SSL=false
uv run server.py
  1. 检查所有必需的环境变量是否正确设置：
# 显示所有当前的 ArgoCD 环境变量
env | grep ARGOCD

贡献

欢迎贡献！如果您想为此项目做出贡献，请打开一个问题或拉取请求。

在贡献时，请遵循以下指南：

  • 确保所有代码包含适当的类型提示
  • 在提交 PR 之前运行 mypy 类型检查
  • 为新功能添加测试
  • 更新文档以反映任何新功能或更改