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 .启动服务器
服务器是通过环境变量配置的。以下是可用的配置选项：
| 环境变量 | 描述 | 默认值 |
|---|---|---|
ARGOCD_TOKEN | ArgoCD API代币 | 无 |
ARGOCD_API_URL | ArgoCD API终点 | https://argocd.example.com/api/v1 |
ARGOCD_VERIFY_SSL | 验证SSL证书 | true |
您可以通过多种方式启动服务器：
# 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扩展服务器
要添加新功能，请执行以下操作：
- 将新工具添加到中的相应模块
tools目录 - 在中注册新工具
server.py - 遵循现有的模式进行参数验证和错误处理
- 更新README.md中的文档
- 添加新功能的测试
故障排除
如果您遇到问题：
- 检查服务器日志（默认情况下启用信息记录）
- 请注意
Processing request of type CallToolRequest是信息性的，不是错误 - 如果使用
mcp dev server.py，MCP检查器将在以下时间自动打开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类型检查
- 添加新功能的测试
- 更新文档以了解任何新功能或更改