ArgoCD MCP

ArgoCD MCP服务器

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

特性

• 身份验证和会话管理:

- 从ArgoCD API检索用户信息 - ArgoCD基于令牌的身份验证 - 服务器设置和配置访问 - 插件信息检索 - 版本信息检索

• 应用程序管理:

- 按项目、名称、命名空间列出和筛选应用程序 - 获取详细的应用程序信息 - 创建、更新和删除应用程序 - 使用可配置选项同步应用程序

• 强大的API客户端:

- URL规范化和智能端点处理 - 全面的错误处理和详细的错误消息 - 可配置的超时和SSL验证 - 令牌安全保护和屏蔽

• 开发者体验:

- 使用mypy进行完全静态类型检查 - 详细的文档和示例 - 基于环境的配置

快速开始

设置

# Clone the repository
git clone https://github.com/severity1/argocd-mcp.git
cd argocd-mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -e .

启动服务器

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

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

# Using MCP dev tools (provides debugging tools)
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
mcp dev server.py

# Using MCP run command
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
mcp run server.py

# Standard method
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
uv run server.py

# Setting multiple environment variables
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
export ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1
export ARGOCD_VERIFY_SSL=false  # Disable SSL verification for self-signed certs
uv run server.py

# Using a .env file
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

# Run in background
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
uv run server.py > server.log 2>&1 & echo $! > server.pid

当通过环境变量提供令牌时，Claude可以使用它，而无需在每个命令中都指定它。

与克劳德联系

使用克劳德代码CLI

# Add the MCP server
claude mcp add argocd-mcp "uv run $(pwd)/server.py"

# With token
claude mcp add argocd-mcp -e ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN -- "uv run $(pwd)/server.py"

# Verify it was added
claude mcp list

# For debugging, you can use MCP Inspector with 'mcp dev' command

使用克劳德桌面

创建一个 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可执行文件的完整路径（使用 which uv 在macOS/Linux或 where uv 在Windows上）
• 为argocd-mcp安装设置正确的目录路径
• 添加您的ArgoCD API代币
• 根据需要配置其他环境变量

此配置告诉告诉您如何使用特定的环境设置自动启动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进行静态类型检查，以提高代码质量并及早发现与类型相关的错误：

# Install mypy
uv pip install mypy

# Run type checking
uv run -m mypy .

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

• 不允许非类型化定义
• 退货警告任何类型
• 检查函数定义的完整性
• 命名空间包支持
• 模块特定配置

项目结构

代码被组织成模块化结构：

argocd-mcp/
├── api/              # API client and communication
│   ├── __init__.py
│   └── client.py     # HTTP client for ArgoCD API
├── models/           # Data models
│   ├── __init__.py
│   └── applications.py # Application data structures
├── tools/            # MCP tools implementation
│   ├── __init__.py
│   ├── session.py    # Session tools (user info)
│   ├── applications.py # Application management tools
│   ├── settings.py   # Server settings tools
│   └── version.py    # Version information tools
├── utils/            # Utility functions
│   ├── __init__.py
├── server.py         # Main server entry point
├── pyproject.toml    # Project configuration and dependencies
└── mypy.ini          # Mypy type checking configuration

扩展服务器

要添加新功能，请执行以下操作：

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

故障排除

如果您遇到问题：

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

# Disable SSL verification
export ARGOCD_VERIFY_SSL=false
uv run server.py

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

# Show all current ArgoCD environment variables
env | grep ARGOCD

贡献

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

投稿时，请遵循以下准则：

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