ArgoCD MCP 服务器

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

Python 类型检查

特征

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

Related MCP server: mcp-gopls

快速入门

设置

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

启动服务器

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

环境变量	描述	默认值
`ARGOCD_TOKEN`	ArgoCD API 令牌	没有任何
`ARGOCD_API_URL`	ArgoCD API 端点	https://argocd.example.com/api/v1
`ARGOCD_VERIFY_SSL`	验证 SSL 证书	真的

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

# 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 可以使用它，而无需在每个命令中指定它。

与克劳德联系

使用 Claude Code 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

创建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 进行静态类型检查，以提高代码质量并尽早发现与类型相关的错误：

# Install mypy uv pip install mypy # Run type checking uv run -m mypy .

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

不允许无类型定义
返回 Any 类型的警告
检查函数定义的完整性
命名空间包支持
模块特定配置

项目结构

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

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

扩展服务器

要添加新功能：

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

故障排除

如果您遇到问题：

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

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

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

# Show all current ArgoCD environment variables env | grep ARGOCD

贡献

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

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

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

argocd-mcp