HUB
Sign inSign up

talkopsai/kargo-mcp-server

By talkopsai

•Updated 3 days ago

MCP server for Kargo continuous promotion — pipeline visibility, freight, and rollbacks

Image
0

317

talkopsai/kargo-mcp-server repository overview

⁠Kargo MCP Server

Let your AI assistant operate Kargo multi-stage promotion pipelines: inspect stages and warehouses, verify and approve freight, promote releases across environments, roll back stages, and diagnose failed promotions without exposing secrets.

⁠Quick Reference

⁠What You Get

  • 20 MCP tools (4 read-only) built for AI agents and MCP clients
  • 18 MCP resources under kargo:// for structured context discovery
  • 5 Agent Skills bundled in /app/skills (browse on GitHub⁠)
  • Container ready: Runs as a minimal non-root image (linux/amd64, linux/arm64) talking directly to the Kargo REST API.
  • Safe by default: starts in read-only mode until you explicitly set MCP_ALLOW_WRITE=true.

⁠Quick Start (MCP Client over stdio)

Use this configuration in Claude Desktop, Cursor, Windsurf, or VS Code (mcp.json / claude_desktop_config.json):

{
  "mcpServers": {
    "kargo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_TRANSPORT=stdio",
        "-e",
        "KARGO_BASE_URL",
        "-e",
        "KARGO_AUTH_MODE",
        "-e",
        "KARGO_STATIC_BEARER_TOKEN",
        "talkopsai/kargo-mcp-server:latest"
      ],
      "env": {
        "KARGO_BASE_URL": "https://kargo.example.com",
        "KARGO_AUTH_MODE": "static",
        "KARGO_STATIC_BEARER_TOKEN": "<your-kargo-token>"
      }
    }
  }
}

Using Claude Code? Register it in one command:

claude mcp add kargo -e KARGO_BASE_URL=https://kargo.example.com -e KARGO_AUTH_MODE=static -e KARGO_STATIC_BEARER_TOKEN=<your-kargo-token> -- docker run -i --rm -e MCP_TRANSPORT=stdio -e KARGO_BASE_URL -e KARGO_AUTH_MODE -e KARGO_STATIC_BEARER_TOKEN talkopsai/kargo-mcp-server:latest

Restart your MCP client and try asking:

  • "Show me the pipeline for the guestbook project. What's running in each stage?"
  • "Promote the latest verified freight to staging."
  • "Why did the last promotion to prod fail?"

⁠Running Standalone (Streamable HTTP)

By default (MCP_TRANSPORT=http), the container starts an MCP Streamable HTTP server on port 8766 so multiple clients can share a single instance:

docker run --rm -p 8766:8766 \
  -e KARGO_BASE_URL=https://kargo.example.com \
  -e KARGO_AUTH_MODE=static \
  -e KARGO_STATIC_BEARER_TOKEN=<your-kargo-token> \
  talkopsai/kargo-mcp-server:latest

Point your MCP client at http://localhost:8766/mcp:

{
  "mcpServers": {
    "kargo": {
      "url": "http://localhost:8766/mcp"
    }
  }
}

⁠Allowing Changes (Write Mode)

Out of the box, the container runs in read-only mode (MCP_ALLOW_WRITE=false). To allow mutations (creating or updating projects, warehouses, stages, promotions, credentials, and RBAC roles), pass -e MCP_ALLOW_WRITE=true to docker run. Even with writes enabled, changes support dry-run previews and destructive operations require explicit confirmation.


⁠Environment Variables

VariableContainer DefaultDescription
KARGO_BASE_URLhttp://localhost:8080Kargo API URL (use http://host.docker.internal:8080 if port-forwarded locally)
KARGO_AUTH_MODEadminAuthentication mode: admin, static, or passthrough
KARGO_ADMIN_PASSWORDnoneAdmin password when KARGO_AUTH_MODE=admin
KARGO_STATIC_BEARER_TOKENnoneBearer token when KARGO_AUTH_MODE=static
KARGO_PROJECTnoneDefault Kargo project name
KARGO_VERIFY_SSLtrueVerify TLS certificates when connecting to Kargo
MCP_ALLOW_WRITEfalseSet to true to enable promotions, approvals, and resource mutations
MCP_TOOLSETSallFilter tools: pipeline, promotion, verification, credentials, rbac, diagnostics, readonly
MCP_TRANSPORThttphttp (standalone server) or stdio (MCP client subprocess)
MCP_PORT8766HTTP listen port inside the container

⁠Available Tools (20)

ToolAccessDescription
kargo_apply_analysis_templateWriteCreate or update an Argo Rollouts AnalysisTemplate or ClusterAnalysisTemplate for Kargo Stage verification.
kargo_apply_project_configWriteConfigure a Kargo ProjectConfig CRD (auto-promotion policies, webhook receivers, and UI links).
kargo_apply_promotion_taskWriteCreate or update a reusable Kargo PromotionTask or ClusterPromotionTask.
kargo_apply_stageWriteCreate or update a Kargo Stage, merging updates with existing Stage spec and validating DAG cycles.
kargo_apply_warehouseWriteCreate or update a Kargo Warehouse with Git, Image, or Helm Chart subscriptions.
kargo_approve_freightWrite (destructive)Manually approve a Freight bundle (by SHA-1 name or alias) for promotion to a target Stage.
kargo_delete_resourceWrite (destructive)Delete a Kargo Stage, Warehouse, PromotionTask, ClusterPromotionTask, or ProjectConfig after confirmation.
kargo_diagnose_stageReadDiagnose a Kargo Stage by correlating conditions, Promotion step traces, Verification AnalysisRuns, holds, and events (N-to-1).
kargo_diagnose_warehouseReadDiagnose a Kargo Warehouse by inspecting artifact discovery status, conditions, and deprecated Kargo v1.9–v1.12 fields (N-to-1).
kargo_manage_credentialsWrite (destructive)Create, update, or delete Kargo repository credentials, generic secrets, or ConfigMaps without exposing secret values.
kargo_manage_freightWrite (destructive)Update a Freight human-friendly alias, manually assemble a Freight item, or delete unused Freight.
kargo_manage_projectWrite (destructive)Create or delete a Kargo Project (cluster-scoped organizational boundary).
kargo_manage_promotionWrite (destructive)Abort a running/pending Kargo Promotion or refresh (wake) a waiting Promotion.
kargo_manage_rolesWrite (destructive)Create or delete a managed Kargo Role, or grant/revoke OIDC user claims and stage permissions.
kargo_manage_verificationWrite (destructive)Re-run (reverify) or abort a Stage's verification AnalysisRun, or delete an AnalysisTemplate.
kargo_promoteWritePromote Freight to a Stage (by SHA-1 name, alias, or origin Warehouse) or to all immediate downstream Stages.
kargo_query_freightReadQuery and filter Kargo Freight bundles in a project by stage availability, origin Warehouse, or alias.
kargo_refreshWriteTrigger immediate reconciliation or artifact discovery on a Warehouse, Stage, Promotion, ProjectConfig, or ClusterConfig.
kargo_rollback_stageWrite (destructive)Roll back a Kargo Stage to a previous known-good Freight using Kargo's roll-forward promotion model (N-to-1).
kargo_trace_freightReadTrace a Freight bundle or versioned artifact across all Stages in a Kargo project (N-to-1).

⁠Bundled Agent Skills (5)

This image also ships step-by-step operational playbooks (SKILL.md) under /app/skills:

To copy the skills onto your workstation for Claude Code or Cursor:

docker run --rm --entrypoint tar talkopsai/kargo-mcp-server:latest -C /app/skills -cf - . | tar -xf - -C ~/.claude/skills/

⁠Support & Community

Tag summary

Content type

Image

Digest

sha256:6e54e0176…

Size

72.6 MB

Last updated

3 days ago

docker pull talkopsai/kargo-mcp-server