MCP 服务器

argocd-mcp

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

README

ArgoCD MCP 服务器

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

功能

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

快速开始

设置

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

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

# 安装依赖
uv pip install -e .

启动服务器

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

环境变量	描述	默认值
`ARGOCD_TOKEN`	ArgoCD API 令牌	None
`ARGOCD_API_URL`	ArgoCD 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: 触发应用程序的同步操作

示例对话

检查用户信息

User: What's my user information in ArgoCD?

Claude: Let me retrieve your user information.

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

You are logged in as 'devops-user'.

获取 ArgoCD 版本

User: What version of ArgoCD is running on the server?

Claude: Let me check the ArgoCD version information.

⏺ 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"
      }

You're running ArgoCD v2.9.3, built on September 15, 2023. It's running on Linux (amd64) with Go 1.20.7, and includes Kustomize v5.1.1 and Helm v3.12.3.

获取 ArgoCD 设置

User: Show me the ArgoCD server settings

Claude: Let me retrieve the ArgoCD server settings for you.

⏺ argocd-mcp:get_settings (MCP)
  ⎿  {
        "clusterSettings": {
          "appLabelKey": "argocd.argoproj.io/instance",
          "controllerNamespace": "argocd",
          "execEnabled": true,
          "statusBadgeEnabled": true,
          "uiBannerContent": "This is a development instance of ArgoCD",
          "url": "https://argocd.example.com"
        }
      }

Here are the key settings for your ArgoCD server:
- URL: https://argocd.example.com
- Controller namespace: argocd
- Exec enabled: Yes
- Status badge enabled: Yes
- UI Banner: "This is a development instance of ArgoCD"

管理应用程序

User: What applications do I have in the "production" project?

Claude: Let me list your applications in the production project.

⏺ 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"},
            }
          }
        ]
      }

You have 3 applications in the production project:
- frontend-app (Synced, Healthy)
- api-service (OutOfSync, Healthy)
- database (Synced, Degraded)

User: Sync the api-service application

Claude: I'll sync the api-service application for you.

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

Application sync initiated successfully. The sync operation is now in progress.

开发

要求

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 类型检查配置

扩展服务器

要添加新功能：

将新工具添加到 tools 目录中的相应模块
在 server.py 中注册新工具
遵循现有的参数验证和错误处理模式
更新 README.md 中的文档
为新功能添加测试

故障排除

如果您遇到问题：

检查服务器日志（默认情况下启用信息日志记录）
请注意，Processing request of type CallToolRequest 仅供参考，不是错误
如果使用 mcp dev server.py，MCP Inspector 将自动在 http://localhost:5173 打开以进行调试
使用服务器日志调试 API 调用和响应
对于自签名证书的 SSL 证书问题：

# 禁用 SSL 验证
export ARGOCD_VERIFY_SSL=false
uv run server.py

检查是否正确设置了所有必需的环境变量：

# 显示所有当前的 ArgoCD 环境变量
env | grep ARGOCD

贡献

欢迎贡献！如果您想为此项目做出贡献，请打开一个 issue 或 pull request。

贡献时，请遵循以下准则：

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