hypen-argocd-mcp

hypen-code/hypen-argocd-mcp

3.2

If you are the rightful owner of hypen-argocd-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A robust, optimized Model Context Protocol (MCP) server for ArgoCD, built with Rust. This server enables AI assistants to interact with ArgoCD APIs through standardized MCP tools.

Tools
9
Resources
0
Prompts
0

ArgoCD MCP Server

A robust, optimized Model Context Protocol (MCP) server for ArgoCD, built with Rust. This server enables AI assistants to interact with ArgoCD APIs through standardized MCP tools.

Features

  • Optimized Response Format: Responses are optimized to minimize context window usage while providing essential information
  • Robust Error Handling: Comprehensive error handling with detailed error messages and graceful degradation
  • Complete Test Coverage: 60+ integration tests with mock ArgoCD API server
  • Stdio Transport: Uses stdio transport for seamless integration with MCP clients
  • Type-Safe: Built with Rust for type safety and performance
  • Version Compatibility: Supports ArgoCD v1.0+ with documented requirements for advanced features

ArgoCD Version Compatibility

FeatureMinimum VersionStatus
Core Tools (list, get, tree, logs, manifests, metadata)ArgoCD v1.0+✅ Fully Supported
list_resource_eventsArgoCD v1.0+✅ Fully Supported
sync_applicationArgoCD v1.0+✅ Fully Supported
rollback_applicationArgoCD v1.0+✅ Fully Supported
server_side_diffArgoCD v2.5+⚠️ Version-Specific
get_application_sync_windowsArgoCD v2.6+⚠️ Version-Specific

Note: Version-specific features will return a 404 error if your ArgoCD instance doesn't support them. This is expected behavior and documented in each tool's description.

Tools

list_applications

Lists ArgoCD applications with optional filters, returning detailed information.

Arguments:

  • name (optional): Filter by application name
  • projects (optional): Filter by project names (array of strings)
  • selector (optional): Label selector to filter applications (e.g., 'env=prod')
  • repo (optional): Filter by repository URL
  • app_namespace (optional): Filter by application namespace

Returns: Optimized application summaries including:

  • Application name and namespace
  • Project
  • Repository URL and target revision
  • Destination server and namespace
  • Sync and health status
  • Auto-sync configuration

list_application_names

Lists only the names of ArgoCD applications. Highly optimized for minimal context usage - perfect for name lookups and auto-correcting typos in application names.

Arguments:

  • projects (optional): Filter by project names (array of strings)
  • selector (optional): Label selector to filter applications (e.g., 'env=prod')
  • repo (optional): Filter by repository URL
  • app_namespace (optional): Filter by application namespace

Returns: A simple list of application names as strings.

Use Cases:

  • Get a quick list of all application names
  • Verify if an application exists
  • Auto-correct typos when user types application names incorrectly
  • Minimal context window usage (~95% smaller than full application details)

get_application

Get detailed information about a specific ArgoCD application by name. Returns comprehensive application details including source repository, destination cluster, sync status, health status, and sync policy configuration.

Arguments:

  • name (required): Application name
  • app_namespace (optional): Application's namespace
  • project (optional): Project identifier
  • refresh (optional): Refresh mode - "normal" or "hard" to force refresh from repository
  • resource_version (optional): Resource version for optimistic concurrency

Returns: Optimized detailed information including:

  • Application name, namespace, and project
  • Creation timestamp and labels
  • Source repository details (URL, path/chart, target revision)
  • Destination cluster and namespace
  • Sync status and revision
  • Health status and message
  • Sync policy configuration (auto-sync, prune, self-heal settings)

Use Cases:

  • Get comprehensive details about a specific application
  • Check application's current sync and health status
  • Review application configuration and source
  • Examine sync policy settings
  • Force refresh application state from repository
  • Troubleshoot application issues with detailed status information

Example Output:

Application: guestbook

Namespace: argocd
Project: default
Created: 2025-01-01T10:00:00Z

Source:
  Repository: https://github.com/argoproj/argocd-example-apps
  Path: guestbook
  Target Revision: HEAD

Destination:
  Server: https://kubernetes.default.svc
  Namespace: default

Status:
  Sync Status: Synced
  Sync Revision: abc123def456
  Health Status: Healthy
  Health Message: All resources are healthy

Sync Policy:
  Auto Sync: Enabled
  Auto Prune: true
  Self Heal: true

Labels:
  env: production
  team: platform

Note: Use refresh: "hard" parameter to force a full refresh of the application state from the repository, which is useful when you need the most up-to-date information.

server_side_diff

Performs server-side diff calculation for an ArgoCD application using dry-run apply. This executes a Server-Side Apply operation in dryrun mode and compares the predicted state with the live state.

Arguments:

  • app_name (required): The application name
  • app_namespace (optional): Application's namespace
  • project (optional): Project identifier
  • target_manifests (optional): Target manifests for comparison (array of YAML/JSON strings)

Returns: Optimized summaries of resources showing:

  • Resource name, kind, and namespace
  • Modified status (boolean indicating if differences exist)
  • Diff summary for modified resources
  • Grouped by modified/in-sync status

Use Cases:

  • Check if an application has configuration drift
  • Preview changes before syncing
  • Validate that admission controllers will accept the changes
  • Identify which specific resources have differences
  • Compare live state with target state without performing actual sync

Example Output:

Server-Side Diff for application 'guestbook'
Total resources: 3, Modified: 1, In sync: 2

Modified Resources:
1. guestbook-ui (Deployment) in namespace 'default'
   Status: Resource has differences between live and target state

In Sync Resources:
1. guestbook-ui (Service) in namespace 'default'
2. redis-master (Deployment) in namespace 'default'

Note: Server-Side Diff is a beta feature (available since ArgoCD v2.10.0). It provides more accurate diff results by involving Kubernetes admission controllers in the calculation.

resource_tree

Get the hierarchical resource tree for an ArgoCD application. Returns a comprehensive view of all Kubernetes resources managed by the application, including their relationships, health status, and metadata.

Arguments:

  • application_name (required): The application name
  • namespace (optional): Filter by resource namespace
  • name (optional): Filter by resource name
  • version (optional): Filter by resource version
  • group (optional): Filter by resource group
  • kind (optional): Filter by resource kind (e.g., "Deployment", "Service")
  • app_namespace (optional): Application's namespace
  • project (optional): Project identifier

Returns: Optimized summary including:

  • Total resource count
  • Orphaned resources count
  • Resources grouped by kind (Deployment, Service, Pod, etc.)
  • Health status summary (Healthy, Degraded, Progressing, etc.)
  • Sample resources (up to 10) with details

Use Cases:

  • Visualize application resource hierarchy
  • Check health status of all resources
  • Identify orphaned resources not managed by the application
  • Understand resource relationships (parent-child)
  • Filter resources by type or namespace
  • Troubleshoot deployment issues
  • Monitor application state

Example Output:

Resource Tree for application 'guestbook'
Total resources: 5
Orphaned resources: 0

Resources by Kind:
  Deployment: 2
  Service: 2
  Pod: 1

Health Summary:
  Healthy: 4
  Progressing: 1

Sample Resources (showing up to 10):
1. guestbook-ui (Deployment) in namespace 'default' - Health: Healthy
   Images: gcr.io/heptio-images/ks-guestbook-demo:0.2
2. guestbook-ui (Service) in namespace 'default' - Health: Healthy - 1 parent(s)
3. redis-master (Deployment) in namespace 'default' - Health: Healthy
   Images: redis:6.2
4. redis-master (Service) in namespace 'default' - Health: Healthy - 1 parent(s)
5. guestbook-ui-7d87c5c5 (Pod) in namespace 'default' - Health: Progressing - 1 parent(s)

Filter Examples:

Filter by kind to see only Deployments:

{
  "application_name": "my-app",
  "kind": "Deployment"
}

Filter by namespace and kind:

{
  "application_name": "my-app",
  "namespace": "production",
  "kind": "Service"
}

list_resource_events

List Kubernetes events for an ArgoCD application or specific resources within an application. Returns comprehensive event information including type (Normal/Warning), reason, message, timestamps, and involved objects. Provides insights into application lifecycle, deployments, and issues.

Arguments:

  • application_name (required): The application name
  • resource_namespace (optional): Filter by resource namespace
  • resource_name (optional): Filter by resource name
  • resource_uid (optional): Filter by resource UID
  • app_namespace (optional): Application's namespace
  • project (optional): Project identifier

Returns: Optimized summary including:

  • Total event count
  • Events grouped by type (Normal, Warning)
  • Events grouped by reason
  • Individual event details (up to 20 recent events shown)
  • Event metadata: reason, message, timestamps, involved objects, source component

Use Cases:

  • Troubleshoot application deployment issues
  • Monitor application lifecycle events
  • Investigate pod failures and scheduling issues
  • Track resource scaling and updates
  • Audit configuration changes
  • Debug image pull errors or resource constraints
  • Monitor application health over time

Example Output:

Events for application 'guestbook'
Total events: 15

Events by Type:
  Normal: 10
  Warning: 5

Events by Reason:
  ScalingReplicaSet: 3
  Started: 4
  Pulled: 3
  FailedScheduling: 2
  BackOff: 3

Recent Events (showing up to 20):

1. [Normal] ScalingReplicaSet - Deployment/guestbook-ui
   Message: Scaled up replica set guestbook-ui-abc to 3
   Count: 5
   First: 2025-01-01T10:00:00Z | Last: 2025-01-01T10:05:00Z
   Source: deployment-controller

2. [Normal] Started - Pod/guestbook-ui-abc-12345
   Message: Started container guestbook
   First: 2025-01-01T10:10:00Z
   Source: kubelet

3. [Warning] FailedScheduling - Pod/guestbook-ui-abc-67890
   Message: 0/5 nodes are available: insufficient cpu
   Count: 10
   First: 2025-01-01T10:15:00Z | Last: 2025-01-01T10:20:00Z
   Source: default-scheduler

... and 12 more events (total: 15)

Filter Examples:

Get all events for a specific resource:

{
  "application_name": "my-app",
  "resource_namespace": "production",
  "resource_name": "my-deployment"
}

Get events for a specific resource by UID:

{
  "application_name": "my-app",
  "resource_uid": "abc-123-def-456"
}

Note: Events are time-limited by Kubernetes (typically retained for 1 hour) and provide the most recent activity for troubleshooting.

pod_logs

Get container logs from pods in an ArgoCD application with intelligent error/warning filtering and log level analysis. Essential for troubleshooting deployments, investigating crashes, and monitoring application behavior.

Arguments:

  • application_name (required): The application name
  • namespace (optional): Pod namespace
  • pod_name (optional): Pod name (if not provided, use kind and resource_name)
  • container (optional): Container name (defaults to first container)
  • since_seconds (optional): Show logs since N seconds ago
  • tail_lines (optional): Number of lines from end (default: 100 for context efficiency)
  • previous (optional): Show previous container logs (if restarted)
  • filter (optional): Server-side text filter
  • kind (optional): Resource kind (e.g., "Deployment", "StatefulSet")
  • group (optional): Resource group
  • resource_name (optional): Resource name (alternative to pod_name)
  • app_namespace (optional): Application namespace
  • project (optional): Project identifier
  • errors_only (optional): Filter to show only errors and potential issues (client-side, recommended for LLM context)

Returns: Intelligent analysis including:

  • Total log lines
  • Error, warning, and potential issue counts
  • Logs grouped by level (FATAL, ERROR, WARNING, INFO, DEBUG)
  • Individual log entries with timestamps and visual indicators
  • Helpful tips for optimization

Key Features:

  • Intelligent Log Level Detection: Automatically detects FATAL, ERROR, WARNING, INFO, DEBUG levels from log content
  • Potential Issue Detection: Identifies problems beyond explicit log levels (exceptions, timeouts, panics, crashes, permission errors, etc.)
  • Error Filtering: Use errors_only: true to show only errors and warnings (saves LLM context)
  • Context-Optimized: Default tail of 100 lines prevents context overflow
  • Visual Indicators: Emoji indicators for quick issue identification (💀 FATAL, ❌ ERROR, ⚠️ WARNING, ℹ️ INFO, 🐛 DEBUG)
  • NDJSON Parsing: Handles ArgoCD's streaming log format

Use Cases:

  • Troubleshoot pod crashes and failures
  • Investigate deployment issues
  • Monitor application errors in real-time
  • Debug connection and timeout problems
  • Find root causes of application failures
  • Analyze log patterns and trends

Example Output:

Pod Logs for application 'my-app'
Pod: my-app-7d87c5c5-abc12
Container: app
Tail Lines: 100

Total lines: 50

🔍 Filtered to show errors and potential issues only

📊 Log Analysis:
  ❌ Errors: 3
  ⚠️  Warnings: 2
  🔍 Potential Issues: 5

Logs by Level:
  ERROR: 3
  WARNING: 2

📝 Log Entries (showing 5):
────────────────────────────────────────────────────────────────────────────────
❌ [2025-01-01T10:15:30Z] ERROR:
   Failed to connect to database: connection timeout

⚠️  [2025-01-01T10:15:35Z] WARNING:
   Retrying connection (attempt 2/5)

❌ [2025-01-01T10:15:40Z] ERROR:
   Connection failed again: unable to resolve hostname

❌ [2025-01-01T10:15:45Z] ERROR:
   Max retries exceeded, giving up

⚠️  [2025-01-01T10:15:50Z] WARNING:
   Service degraded due to database unavailability
────────────────────────────────────────────────────────────────────────────────

💡 Tip: Increase 'tail_lines' to see more logs or use 'since_seconds' for time-based filtering

Filter Examples:

Get all logs (unfiltered):

{
  "application_name": "my-app",
  "pod_name": "my-app-pod",
  "tail_lines": 100
}

Get only errors and warnings (recommended for troubleshooting):

{
  "application_name": "my-app",
  "pod_name": "my-app-pod",
  "errors_only": true
}

Get logs from a specific container:

{
  "application_name": "my-app",
  "pod_name": "my-app-pod",
  "container": "sidecar",
  "tail_lines": 50
}

Get logs since 5 minutes ago:

{
  "application_name": "my-app",
  "pod_name": "my-app-pod",
  "since_seconds": 300
}

Get logs for a Deployment (auto-selects pod):

{
  "application_name": "my-app",
  "kind": "Deployment",
  "resource_name": "my-deployment",
  "errors_only": true
}

Detected Issue Patterns: The tool automatically detects potential issues using these keywords:

  • Error levels: FATAL, CRITICAL, ERROR, ERR
  • Warning levels: WARN, WARNING
  • Exceptions: exception, panic, crash
  • Failures: failed, timeout, unable to, cannot
  • Access issues: refused, denied, permission denied

Performance Tips:

  • Use errors_only: true to reduce context usage by 70-90%
  • Default tail_lines: 100 balances detail with context efficiency
  • Use since_seconds for time-scoped troubleshooting
  • Combine filter (server-side) with errors_only (client-side) for maximum efficiency

revision_metadata

Get metadata (author, date, message, tags) for a specific revision of an ArgoCD application. Returns commit information including author, timestamp, commit message, associated Git tags, and signature verification status. Useful for tracking changes, auditing deployments, and understanding revision history.

Arguments:

  • application_name (required): The application name
  • revision (required): Revision/commit hash
  • app_namespace (optional): Application namespace
  • project (optional): Project identifier
  • source_index (optional): Source index (for multi-source applications)
  • version_id (optional): Version ID from historical data (for multi-source applications)

Returns: Optimized summary including:

  • Author and date of the revision
  • Short and full commit messages
  • Number of tags and associated tags
  • Signature status (signed/not signed) and summary

Use Cases:

  • Track changes and audit deployments
  • Understand revision history and commit details
  • Verify commit authorship and integrity
  • Identify associated Git tags for a revision
  • Debug issues related to specific code versions

Example Output:

Revision Metadata for application 'guestbook' at revision 'abc123def456'

Author: John Doe <john.doe@example.com>
Date: 2025-10-27T10:30:00Z

Commit Message:
  feat: Add new feature

Full Message:
  feat: Add new feature

  This commit introduces a brand new feature to the application.

Tags (2):
  - v1.2.0
  - release-candidate

Signature Status: Valid signature

get_application_sync_windows

Get synchronization windows for an ArgoCD application. Returns a list of configured sync windows, including their schedule, duration, and affected applications/namespaces/clusters. Useful for understanding when an application can be synced or is blocked from syncing.

Arguments:

  • application_name (required): The application name
  • app_namespace (optional): Application namespace
  • project (optional): Project identifier

Returns: Optimized summary including:

  • Total number of sync windows
  • Details for each sync window:
    • kind: Type of sync window (e.g., "allow", "deny")
    • schedule: Cron schedule for the window
    • duration: Duration of the window (e.g., "1h", "30m")
    • applications: List of application names affected by the window
    • namespaces: List of namespaces affected by the window
    • clusters: List of cluster URLs affected by the window
    • manual_sync_enabled: Whether manual sync is allowed during the window
    • start_time: Start time of the window (RFC3339 format)
    • end_time: End time of the window (RFC3339 format)

Use Cases:

  • Determine when an application is allowed or denied to sync
  • Identify maintenance windows or blackout periods
  • Understand which applications, namespaces, or clusters are affected by specific sync policies
  • Verify manual synchronization permissions during a window

Example Output:

Sync Windows for application 'my-app' (2 total):

1. Kind: allow
   Schedule: 0 0 * * *
   Duration: 1h
   Start Time: 2025-01-01T00:00:00Z
   End Time: 2025-01-01T01:00:00Z
   Manual Sync Enabled: true
   Applications: guestbook, helm-app
   Namespaces: default, staging
   Clusters: https://kubernetes.default.svc

2. Kind: deny
   Schedule: 0 2 * * *
   Duration: 30m
   Start Time: 2025-01-01T02:00:00Z
   End Time: 2025-01-01T02:30:00Z
   Manual Sync Enabled: false
   Applications: backend-api
   Namespaces: backend-prod

sync_application

Sync an ArgoCD application to its target state in Git. This operation deploys or updates the application resources to match what's defined in the Git repository. Note: This is a write operation and is blocked in read-only mode.

Arguments:

  • application_name (required): Name of the application to sync
  • revision (optional): Specific revision to sync to (defaults to target revision in app spec)
  • dry_run (optional): If true, preview the sync without actually performing it (default: false)
  • prune (optional): Whether to prune resources that are no longer defined in Git (default: false)
  • force (optional): Use force apply to override any conflicts (default: false)
  • resources (optional): Specific resources to sync (if not specified, syncs all resources)
  • sync_options (optional): Sync options array (e.g., ["Validate=false", "CreateNamespace=true"])
  • retry (optional): Retry configuration (limit, backoff_duration, backoff_max_duration, backoff_factor)
  • app_namespace (optional): Application namespace
  • project (optional): Project identifier

Returns: Optimized summary including:

  • Application name
  • Whether the operation was a dry-run
  • Current sync status and revision after sync
  • Current health status after sync
  • Target revision that was synced to
  • Whether prune/force were enabled
  • Sync options that were applied
  • Number of resources synced (if partial sync)

Use Cases:

  • Deploy new application versions from Git
  • Update application configuration
  • Fix configuration drift
  • Preview changes with dry-run mode
  • Sync only specific resources (partial sync)
  • Force sync to override conflicts
  • Clean up orphaned resources with prune

Example Output:

Sync Completed for application 'guestbook'

Target Revision: HEAD
Current Sync Revision: abc123def456

Status:
  Sync Status: Synced
  Health Status: Progressing

Configuration:
  Dry Run: false
  Prune Enabled: false
  Force Enabled: false
  Resources Synced: all

✅ Sync completed successfully.
    Monitor the application to ensure it reaches the desired state.

Usage Examples:

Basic sync:

{
  "application_name": "guestbook"
}

Dry-run to preview changes:

{
  "application_name": "guestbook",
  "dry_run": true
}

Sync to specific revision:

{
  "application_name": "guestbook",
  "revision": "v1.2.3"
}

Sync with prune:

{
  "application_name": "guestbook",
  "prune": true
}

Sync specific resources only:

{
  "application_name": "guestbook",
  "resources": [
    {
      "group": "apps",
      "kind": "Deployment",
      "name": "guestbook-ui",
      "namespace": "default"
    }
  ]
}

Sync with options:

{
  "application_name": "guestbook",
  "sync_options": ["Validate=false", "CreateNamespace=true"]
}

Common Sync Options:

  • Validate=false - Skip kubectl validation
  • CreateNamespace=true - Create namespace if it doesn't exist
  • PruneLast=true - Prune resources after all other resources are synced
  • ApplyOutOfSyncOnly=true - Only apply out-of-sync resources
  • ServerSideApply=true - Use server-side apply
  • Replace=true - Use replace instead of apply

Best Practices:

  1. Always use dry-run first: Preview the sync with dry_run: true before executing, especially in production
  2. Monitor after sync: Watch the application to ensure it reaches the desired state
  3. Be cautious with force: Only use force when you understand the implications
  4. Be careful with prune: Pruning removes resources - ensure you know what will be deleted
  5. Use selective sync for large apps: Sync specific resources when you only need to update certain components
  6. Configure retries appropriately: Use retry configuration for unreliable environments
  7. Check sync windows: Verify the application isn't in a blocked sync window before syncing

Read-Only Mode: This tool is a write operation and is blocked in read-only mode. You will receive an error if you try to use it when ARGOCD_READ_ONLY=true.

See for detailed documentation, advanced examples, and all sync options.

get_application_history

Get deployment history for an ArgoCD application. Returns a list of all deployments with history IDs, revisions, timestamps, and initiator information. Essential for rollback operations.

Arguments:

  • application_name (required): The application name
  • app_namespace (optional): Application's namespace
  • project (optional): Project identifier

Returns: Optimized summary including:

  • Total number of deployments
  • History entries (up to 20 most recent, sorted newest first):
    • History ID (required for rollback)
    • Git revision (shortened for display, full hash in JSON)
    • Deployment timestamp
    • Deploy duration (if available)
    • Who initiated (username or "Automated")
    • Source repository and path/chart
    • Target revision (branch/tag)
    • Current deployment marker (👉)
    • Automated deployment indicator (🤖)

Use Cases:

  • Get history IDs for rollback operations (most critical - required by rollback_application)
  • Audit deployments and track who deployed what
  • Understand deployment timeline and progression
  • Identify automated vs manual deployments
  • Track source changes across deployments
  • Troubleshoot issues by correlating with specific deployments
  • Verify current deployment status

Example Output:

📜 Deployment History for 'guestbook'
════════════════════════════════════════════════════════════════════════════════

Total deployments: 5

────────────────────────────────────────────────────────────────────────────────

👉 1. History ID: 5 (Current)
   Revision: ghi789jk (ghi789jkl012345678901234567890123456)
   Deployed: 2025-01-05T10:30:00Z
   Duration: from 2025-01-05T10:29:00Z to 2025-01-05T10:30:00Z
   Initiated by: john.doe
   Repository: https://github.com/argoproj/argocd-example-apps
   Path: guestbook
   Target Revision: v2.0

────────────────────────────────────────────────────────────────────────────────

   2. History ID: 4
   Revision: def456ab (def456abc789012345678901234567890123)
   Deployed: 2025-01-04T14:30:00Z
   Initiated by: Automated 🤖
   Repository: https://github.com/argoproj/argocd-example-apps
   Path: guestbook
   Target Revision: main

────────────────────────────────────────────────────────────────────────────────

💡 Tips:
   - Use the History ID with 'rollback_application' to revert to a previous version
   - Current deployment is marked with 👉
   - 🤖 indicates automated deployments

Rollback Workflow:

1. get_application_history(application_name: "my-app")
   → Get history IDs and find the version to rollback to

2. rollback_application(application_name: "my-app", id: 4)
   → Rollback to history ID 4 from step 1

See for detailed documentation, workflows, and examples.

refresh_application

Refresh an ArgoCD application from the Git repository. Forces ArgoCD to re-fetch manifests and recompute sync status. This is a read-only operation that does not modify cluster state - it only updates ArgoCD's cached view.

Arguments:

  • application_name (required): The application name
  • refresh_type (optional): "normal" or "hard" (default: "hard")
    • "normal": Regular refresh from cache
    • "hard": Force refresh from Git repository
  • app_namespace (optional): Application's namespace
  • project (optional): Project identifier

Returns: Before/after comparison showing:

  • Sync status (before/after) with change indicator
  • Health status (before/after) with change indicator
  • Sync revision (before/after) if changed
  • Repository URL and target revision
  • Summary of what changed
  • Visual indicators (🔄 for changed, ✓ for unchanged)

Use Cases:

  • Resolve stale sync status (most common - fix "stuck" applications)
  • Update ArgoCD after pushing to Git
  • Troubleshoot applications not updating
  • Verify configuration changes are detected
  • Fix cache issues
  • Pre-sync verification
  • Detect new Git commits

Example Output:

🔄 Refreshed Application 'guestbook'
════════════════════════════════════════════════════════════════════════════════

Refresh Type: hard
Repository: https://github.com/argoproj/argocd-example-apps
Target Revision: HEAD

────────────────────────────────────────────────────────────────────────────────

📊 Status Comparison:

🔄  Sync Status:
   Before: OutOfSync
   After:  Synced
   ➜ Changed!

✓  Health Status:
   Before: Healthy
   After:  Healthy
   ➜ No change

────────────────────────────────────────────────────────────────────────────────

✅ Refresh completed - Application state was updated

Changes detected in: sync status

💡 Tips:
   - Refresh does not modify cluster resources, only ArgoCD's cache
   - Use 'hard' refresh to force re-fetch from Git repository
   - If sync status changed to 'OutOfSync', use 'sync_application' to deploy

Common Scenarios:

  1. After Git Push: Force ArgoCD to detect new commits

    {
  "application_name": "my-app",
  "refresh_type": "hard"
}

  2. Stuck Application: Fix applications that appear frozen

    {
  "application_name": "stuck-app",
  "refresh_type": "hard"
}

  3. Pre-Deployment Check: Refresh before syncing

    1. refresh_application → Get latest from Git
2. Check if OutOfSync
3. sync_application → Deploy if needed

Important Notes:

  • Read-only operation: Never modifies cluster resources
  • Safe to run anytime: Only updates ArgoCD's cache
  • Not a deployment: Refresh ≠ Sync (use sync_application to deploy)
  • Available in read-only mode: Can be used when ARGOCD_READ_ONLY=true

See for detailed documentation, workflows, and troubleshooting scenarios.

get_resource

Get a specific Kubernetes resource from an ArgoCD application. Returns detailed resource manifest including metadata, spec, and status.

Arguments:

  • application_name (required): The application name
  • resource_name (required): The name of the specific resource to retrieve
  • version (required): The Kubernetes API version (e.g., "v1", "apps/v1")
  • kind (required): The resource kind (e.g., "Pod", "Service", "Deployment")
  • namespace (optional): The namespace of the resource
  • group (optional): The API group (empty for core resources, "apps" for deployments, etc.)
  • app_namespace (optional): The namespace of the ArgoCD application
  • project (optional): The ArgoCD project identifier

Returns: Optimized summary including:

  • Resource identification (name, kind, version, group, namespace)
  • Manifest summary with parsed metadata (labels, annotations, creation time, status)
  • Full manifest (first 50 lines shown, with indication if truncated)

Use Cases:

  • Inspect the current state of a specific pod, deployment, service, or other Kubernetes resource
  • Review resource configuration details
  • Verify resource status and health
  • Troubleshoot issues with specific resources
  • Examine resource labels, annotations, and metadata

Example Output:

Resource: nginx-deployment (Deployment)
Application: production-app
Version: v1
Group: apps
Namespace: production

Manifest Summary:
  API Version: apps/v1
  Kind: Deployment
  Name: nginx-deployment
  Namespace: production
  Labels (3):
    app: nginx
    env: production
    version: 1.0
  Annotations Count: 2
  Created: 2025-01-01T00:00:00Z
  Status: 3/3 replicas ready

📄 Full Manifest:
────────────────────────────────────────────────────────────────────────────────
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: production
...

See for detailed documentation and examples.

patch_resource

Patch a Kubernetes resource in an ArgoCD application using JSON patch, merge patch, or strategic merge patch formats. Note: This is a write operation and is blocked in read-only mode.

Arguments:

  • application_name (required): The application name
  • resource_name (required): The name of the resource to patch
  • version (required): The Kubernetes API version (e.g., "v1", "apps/v1")
  • kind (required): The resource kind (e.g., "Deployment", "Service", "ConfigMap")
  • patch (required): The patch content as a JSON string
  • namespace (optional): The namespace of the resource
  • group (optional): The API group (empty for core resources)
  • patch_type (optional): Patch strategy type (json-patch, merge-patch, strategic-merge-patch)
  • app_namespace (optional): The namespace of the ArgoCD application
  • project (optional): The ArgoCD project identifier

Returns: Optimized summary including:

  • Patch confirmation and resource identification
  • Updated manifest summary with parsed metadata
  • Full updated manifest (first 50 lines shown)

Use Cases:

  • Scale deployments by updating replica count
  • Update container images in deployments
  • Add or modify labels and annotations
  • Update environment variables in pods
  • Modify ConfigMap or Secret data
  • Change resource limits and requests
  • Update service ports or selectors

Common Patch Types:

  • application/json-patch+json: RFC 6902 JSON Patch for precise operations
  • application/merge-patch+json: RFC 7396 Merge Patch for simple merging
  • application/strategic-merge-patch+json: Kubernetes Strategic Merge (default, recommended)

Example - Scale Deployment:

{
  "application_name": "backend-app",
  "namespace": "production",
  "resource_name": "api-deployment",
  "version": "v1",
  "group": "apps",
  "kind": "Deployment",
  "patch": "{\"spec\": {\"replicas\": 5}}",
  "patch_type": "application/merge-patch+json"
}

Example Output:

✅ Patched Resource: api-deployment (Deployment)
Application: production-app
Version: v1
Group: apps
Namespace: production

Updated Manifest Summary:
  API Version: apps/v1
  Kind: Deployment
  Name: api-deployment
  Namespace: production
  Labels (4):
    app: api
    env: production
    version: 2.0
    patched: true
  Status: 5/5 replicas ready

📄 Updated Manifest:
────────────────────────────────────────────────────────────────────────────────
apiVersion: apps/v1
kind: Deployment
...

💡 Tip: Monitor the resource to ensure it reaches the desired state.

Important Notes:

  • Changes made via patch_resource may be overwritten by ArgoCD if the application is synced and the change conflicts with Git
  • For permanent changes, consider updating the Git repository and using sync_application
  • This operation is disabled when ARGOCD_READ_ONLY=true

See for detailed documentation, patch strategy guide, and advanced examples.

rollback_application

Rollback an ArgoCD application to a previous deployed version by History ID. This operation reverts the application to a specific point in its deployment history. Note: This is a write operation and is blocked in read-only mode.

Arguments:

  • application_name (required): Name of the application to rollback
  • id (required): History ID to rollback to. Use 0 to rollback to the previous version
  • dry_run (optional): If true, preview the rollback without actually performing it (default: false)
  • prune (optional): Whether to prune resources that are no longer defined in the target revision (default: false)
  • app_namespace (optional): Application namespace
  • project (optional): Project identifier

Returns: Optimized summary including:

  • Application name
  • History ID that was rolled back to
  • Whether the operation was a dry-run
  • Current sync status and revision after rollback
  • Current health status after rollback
  • Target revision after rollback
  • Whether pruning was enabled

Use Cases:

  • Quickly revert to a previous working version after a failed deployment
  • Rollback to a known-good state during incidents
  • Preview rollback effects with dry-run mode before executing
  • Remove orphaned resources with prune option
  • Audit and track rollback operations

Example Output:

Rollback Completed for application 'guestbook'

Rolled back to History ID: 5
Target Revision: abc123
Current Sync Revision: abc123def456

Status:
  Sync Status: Synced
  Health Status: Healthy

Options:
  Dry Run: false
  Prune Enabled: false

✅ Rollback completed successfully.
    Monitor the application to ensure it reaches the desired state.

Dry Run Example:

Rollback (Dry Run) for application 'guestbook'

Rolled back to History ID: 3
Target Revision: v1.0.0

Status:
  Sync Status: OutOfSync
  Health Status: Healthy

Options:
  Dry Run: true
  Prune Enabled: false

⚠️  Note: This was a dry run. No actual changes were made.
    Run without dry_run=true to perform the actual rollback.

Usage Examples:

Basic rollback to specific history ID:

{
  "application_name": "guestbook",
  "id": 5
}

Rollback to previous version (ID 0):

{
  "application_name": "guestbook",
  "id": 0
}

Preview rollback with dry-run:

{
  "application_name": "guestbook",
  "id": 3,
  "dry_run": true
}

Rollback with pruning:

{
  "application_name": "guestbook",
  "id": 5,
  "prune": true
}

Best Practices:

  1. Always use dry-run first: Preview the rollback with dry_run: true before executing
  2. Monitor after rollback: Watch the application to ensure it reaches the desired state
  3. Check history: Use revision_metadata to verify the correct history ID
  4. Be cautious with prune: Only enable pruning if you're sure you want to remove resources
  5. Document rollbacks: Keep track of why and when rollbacks are performed

Read-Only Mode: This tool is a write operation and is blocked in read-only mode. You will receive an error if you try to use it when ARGOCD_READ_ONLY=true.

See for detailed documentation and additional examples.

Configuration

The server requires the following environment variables:

Required Variables

  • ARGOCD_BASE_URL: The base URL of your ArgoCD server (e.g., https://argocd.example.com)
  • ARGOCD_ACCESS_TOKEN: Your ArgoCD API access token

Optional Variables

  • ARGOCD_INSECURE (optional): Set to true to skip TLS certificate verification (useful for self-signed certificates)
  • ARGOCD_READ_ONLY (optional): Set to true to enforce read-only mode (default: false)

Read-Only Mode

The server supports a read-only mode that can be enabled by setting the ARGOCD_READ_ONLY environment variable to true. When enabled:

  • ✅ All read-only tools continue to work (GET requests)
  • ❌ Write operations like rollback_application are blocked
  • ✅ Server information displays "READ-ONLY MODE" indicator
  • ✅ Provides additional safety for production environments
  • ✅ Useful for audit/compliance requirements

Write Operations (Blocked in Read-Only Mode):

  • sync_application - Sync an application to its target state in Git
  • rollback_application - Rollback an application to a previous version
  • patch_resource - Patch a Kubernetes resource in an application

Read Operations (Always Available):

  • All other tools (list, get, tree, logs, manifests, metadata, events, sync_windows, get_resource, get_application_history, refresh_application, etc.)

The read-only mode is useful for:

  • Production monitoring and troubleshooting without risk of accidental changes
  • Audit and compliance requirements
  • Providing safe access to junior team members
  • Explicit documentation of access level
  • Enhanced security posture
# Enable read-only mode
export ARGOCD_READ_ONLY=true

# Disable read-only mode (default)
export ARGOCD_READ_ONLY=false

TLS/SSL Configuration

If your ArgoCD server uses self-signed certificates or certificates that are not trusted by the system, you can disable TLS certificate verification:

export ARGOCD_INSECURE=true

Security Warning: Only use ARGOCD_INSECURE=true in development/testing environments or with internal ArgoCD servers. For production use, it's recommended to:

  • Use properly signed certificates from a trusted CA
  • Add your organization's CA certificate to the system trust store
  • Use argocd login --insecure only when absolutely necessary

Getting an ArgoCD Access Token

  1. Log in to your ArgoCD instance:

    argocd login <ARGOCD_SERVER>

  2. Generate an account token:

    argocd account generate-token

Installation

Prerequisites

  • Rust 1.70 or later (for building)
  • Python 3.8+ (for running via wrapper)

Building

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

# Build the Rust binary
cargo build --release

Deploying to Another Location

After building, you can deploy the server to any location. The server consists of two components:

  1. Python wrapper (argocd_mcp_server.py)
  2. Rust binary (target/release/argocd-mcp-server)

Important: The Python wrapper looks for the binary in specific locations relative to itself:

  • bin/argocd-mcp-server (recommended for deployment)
  • argocd-mcp-server (same directory as wrapper)
  • target/release/argocd-mcp-server (development only)
Quick Installation

Use the provided installation script:

# Install to default location (~/.local/bin/argocd-mcp-server)
./install.sh

# Or install to custom location
./install.sh /path/to/installation/directory
Manual Installation
# Create installation directory
mkdir -p /path/to/install/bin

# Copy files
cp argocd_mcp_server.py /path/to/install/
cp target/release/argocd-mcp-server /path/to/install/bin/

# Make executable
chmod +x /path/to/install/argocd_mcp_server.py
chmod +x /path/to/install/bin/argocd-mcp-server

See for detailed installation instructions, troubleshooting, and deployment best practices.

Usage

Running the Server

The server can be run in two ways:

Method 1: Via Python Wrapper (Recommended - Most Compatible)

This method is compatible with all MCP frameworks that require standard executables:

# Set environment variables
export ARGOCD_BASE_URL=https://your-argocd-server.com
export ARGOCD_ACCESS_TOKEN=your-access-token-here

# Run via Python wrapper
python3 argocd_mcp_server.py
Method 2: Direct Rust Binary

For direct execution or testing (not supported by all MCP frameworks):

# Set environment variables
export ARGOCD_BASE_URL=https://your-argocd-server.com
export ARGOCD_ACCESS_TOKEN=your-access-token-here

# Run the binary directly
./target/release/argocd-mcp-server
# OR
cargo run --release

Using with MCP Inspector

Test the server using the MCP Inspector:

# Via Python wrapper (recommended)
npx @modelcontextprotocol/inspector python3 argocd_mcp_server.py

# OR via direct binary
npx @modelcontextprotocol/inspector ./target/release/argocd-mcp-server

Integration with Claude Desktop / Claude Code

Add to your Claude Desktop/Code configuration (.mcp.json or claude_desktop_config.json):

Option 1: Using Python Wrapper (Recommended - Most Compatible)
{
  "mcpServers": {
    "argocd": {
      "command": "python3",
      "args": ["/absolute/path/to/argocd-mcp-server/argocd_mcp_server.py"],
      "env": {
        "ARGOCD_BASE_URL": "https://your-argocd-server.com",
        "ARGOCD_ACCESS_TOKEN": "your-access-token-here",
        "ARGOCD_INSECURE": "true"
      }
    }
  }
}
Option 2: Direct Binary (If your framework supports it)
{
  "mcpServers": {
    "argocd": {
      "command": "/absolute/path/to/argocd-mcp-server/target/release/argocd-mcp-server",
      "env": {
        "ARGOCD_BASE_URL": "https://your-argocd-server.com",
        "ARGOCD_ACCESS_TOKEN": "your-access-token-here",
        "ARGOCD_INSECURE": "true"
      }
    }
  }
}
Option 3: Using uvx/pipx (After publishing to PyPI)
{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": ["argocd-mcp-server"],
      "env": {
        "ARGOCD_BASE_URL": "https://your-argocd-server.com",
        "ARGOCD_ACCESS_TOKEN": "your-access-token-here",
        "ARGOCD_INSECURE": "true"
      }
    }
  }
}

Notes:

  • Use Option 1 (Python wrapper) - Most compatible with all MCP frameworks
  • Only include "ARGOCD_INSECURE": "true" if your ArgoCD server uses self-signed certificates
  • The wrapper adds minimal overhead (~1-2ms) while maintaining Rust performance
  • Always use absolute paths - Replace /absolute/path/to/ with your actual path

Development

Running Tests

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_list_all_applications

Project Structure

argocd-mcp-server/
├── src/
│   ├── main.rs                  # Entry point with stdio transport
│   ├── lib.rs                   # Library exports
│   ├── argocd_client.rs         # ArgoCD API client
│   ├── models.rs                # Data models (optimized for context efficiency)
│   └── tools.rs                 # MCP tool implementations
├── tests/
│   └── integration_test.rs      # Integration tests with mock server
├── argocd_mcp_server.py         # Python wrapper (RECOMMENDED)
├── setup.py                     # Python package setup
├── pyproject.toml               # Python project configuration
├── Cargo.toml                   # Rust package configuration
├── Cargo.lock                   # Rust dependency lock
└── README.md

Architecture

Components

  1. ArgoCD Client (argocd_client.rs)

    • Handles HTTP communication with ArgoCD API
    • Implements authentication and error handling
    • Provides both optimized and full response methods

  2. Data Models (models.rs)

    • Type-safe models for ArgoCD objects
    • Optimized summary format to reduce context usage
    • Comprehensive deserialization with proper field mappings

  3. MCP Tools (tools.rs)

    • Implements MCP tool interface using #[tool] macros
    • Handles tool routing and parameter validation
    • Formats responses for optimal readability

Response Optimization

The server uses ApplicationSummaryOutput to provide only essential fields:

  • Reduces response size by ~70% compared to full application objects
  • Includes all critical information for decision-making
  • Provides both human-readable and JSON formats

Testing

Comprehensive test suite includes:

  • Unit tests for client creation and validation
  • Integration tests with mock ArgoCD API server (using wiremock)
  • Error handling tests (authentication, network, server errors)
  • Filter and pagination tests
  • Empty response handling

API Compatibility

This server is compatible with ArgoCD API v1alpha1. It has been tested with:

  • ArgoCD 2.x API endpoints
  • Standard ArgoCD authentication

Performance

  • Startup Time: < 100ms
  • Response Time: Typically < 500ms for listing applications (depends on ArgoCD server)
  • Memory Usage: ~10MB base memory footprint
  • Concurrency: Fully async using Tokio runtime

Troubleshooting

Common Issues

  1. "ArgoCD client not initialized"

    • Ensure ARGOCD_BASE_URL and ARGOCD_ACCESS_TOKEN are set
    • Check that the environment variables are exported before running

  2. Authentication errors

    • Verify your access token is valid: argocd account get-user-info
    • Generate a new token if needed

  3. Connection timeout

    • Check network connectivity to ArgoCD server
    • Verify the base URL is correct and accessible

  4. TLS/SSL certificate errors

    • Error: "Failed to send request to ArgoCD API"
    • Common cause: Self-signed or untrusted certificates
    • Solution: Set ARGOCD_INSECURE=true in your environment configuration
    • Alternative: Add your organization's CA certificate to the system trust store

Debug Logging

Enable debug logging:

RUST_LOG=debug cargo run

Security Considerations

  • Store access tokens securely (use environment variables or secret managers)
  • Never commit tokens to version control
  • Use HTTPS for ArgoCD server connections
  • Regularly rotate access tokens
  • Consider using service accounts with minimal required permissions

Future Enhancements

Potential additions:

  • Additional tools (sync_application, rollback_application, etc.)
  • Application creation and updates
  • Detailed resource status queries
  • Webhook support for real-time updates
  • Caching layer for improved performance
  • Application manifest generation

Contributing

Contributions are welcome! Please ensure:

  • All tests pass (cargo test)
  • Code is formatted (cargo fmt)
  • No clippy warnings (cargo clippy)

Acknowledgments