Skip to main content

Kargo logo

Kargo MCP Server & Agent Plugin

An Agent Plugin v1.0.0 package that pairs 5 Agent Skills with a 20-tool, 18-resource execution-only MCP server for Kargo v1.10+ (tested against v1.12.5) progressive delivery pipelines.

PyPI Python 3.12+ License MCP Kargo v1.10+


Let your AI assistant manage Kargo promotion pipelines: see what's deployed where, promote and approve freight, roll back stages, and find out why a promotion failed. Secrets stay on the server.

What you get

  • 20 MCP tools (4 read-only) that work against your live Kargo setup
  • 18 resources your assistant can read for context, under kargo://
  • 5 Agent Skills: step-by-step playbooks that teach your assistant how to use the tools well
  • Safe by default: only read-only tools are loaded until you turn on writes, and changes are previewed or confirmed before they happen

Quick start

You'll need:

  • Python 3.12+ and uv, or Docker
  • A Kargo API URL and credentials (admin password or a bearer token)

1. Add the server to your MCP client. For Claude Desktop, Cursor, Windsurf, and most other clients, add this to your MCP config file:

{
  "mcpServers": {
    "kargo": {
      "command": "uvx",
      "args": [
        "--from",
        "talkops-kargo-mcp-server",
        "kargo-mcp-server"
      ],
      "env": {
        "KARGO_BASE_URL": "https://kargo.example.com",
        "KARGO_AUTH_MODE": "static",
        "KARGO_STATIC_BEARER_TOKEN": "<your-kargo-token>"
      }
    }
  }
}

Using Claude Code? Run this instead:

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> -- uvx --from talkops-kargo-mcp-server kargo-mcp-server

uvx downloads talkops-kargo-mcp-server from PyPI and runs it, so there's nothing else to install. Prefer a normal install? Run pip install talkops-kargo-mcp-server and use kargo-mcp-server as the command.

Prefer Docker? Pull talkopsai/kargo-mcp-server from Docker Hub—no Python setup needed:

{
  "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>"
      }
    }
  }
}

2. Restart your client and try asking:

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

Allowing changes

Out of the box the server is read-only. To let your assistant make changes (creating and changing projects, warehouses, stages, promotions, credentials, and roles), add "--allow-write" to args (or pass -e MCP_ALLOW_WRITE=true to docker run). Even then, changes are previewed first and destructive actions ask for confirmation.

Configuration

Set these as environment variables (the env block in your client config, or -e with docker run) or pass the matching flag.

Variable Flag Default What it does
KARGO_BASE_URL --kargo-url http://localhost:8080 Your Kargo API URL
KARGO_AUTH_MODE --auth-mode admin admin, static, or passthrough
KARGO_ADMIN_PASSWORD — none Password when using admin mode
KARGO_STATIC_BEARER_TOKEN — none Token when using static mode
KARGO_PROJECT --project none Default project
KARGO_VERIFY_SSL --insecure-skip-tls-verify true Verify the Kargo TLS certificate
MCP_ALLOW_WRITE --allow-write false Enable tools that change Kargo
MCP_TOOLSETS --toolsets all Limit tools: pipeline, promotion, verification, credentials, rbac, diagnostics, readonly
MCP_TRANSPORT --transport stdio stdio or http
MCP_PORT --port 8766 Port when using HTTP

Run uvx --from talkops-kargo-mcp-server kargo-mcp-server --help to see every option.

Running over HTTP

To share one server between several clients or run it remotely, start it in HTTP mode with Docker or uvx:

# With Docker (starts in HTTP mode by default)
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

# Or with uvx
MCP_TRANSPORT=http MCP_PORT=8766 uvx --from talkops-kargo-mcp-server kargo-mcp-server

Then point your client at http://localhost:8766/mcp:

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

Agent Skills

Skills live in skills/. Each one is a SKILL.md playbook (plus optional references/ and offline scripts/) that teaches your AI assistant how to do a job safely, while the MCP server does the actual work. Tools are the hands, skills are the know-how.

To use them, copy the folders into your assistant's skills directory, for example:

git clone https://github.com/talkops-ai/talkops-mcp.git
cp -r talkops-mcp/src/kargo-mcp-server/skills/* ~/.claude/skills/

This folder is also a portable Agent Plugin (plugin.json + mcp.json + skills/), so plugin-aware clients can load the server and skills together.

Skill Use it to
onboarding-kargo-pipelines Set up projects, warehouses, stages, and promotion steps.
promoting-and-approving-freight Check which freight can move forward, approve it, and promote it.
rolling-back-kargo-stages Roll a stage back to its last good freight in an emergency.
troubleshooting-kargo-pipelines Find out why a warehouse, promotion, or verification failed.
managing-kargo-credentials-and-access Manage repository credentials and roles without exposing secrets.

Reference

All 20 tools
Tool Access What it does
kargo_apply_analysis_template Write Create or update an Argo Rollouts AnalysisTemplate or ClusterAnalysisTemplate for Kargo Stage verification.
kargo_apply_project_config Write Configure a Kargo ProjectConfig CRD (auto-promotion policies, webhook receivers, and UI links).
kargo_apply_promotion_task Write Create or update a reusable Kargo PromotionTask or ClusterPromotionTask.
kargo_apply_stage Write Create or update a Kargo Stage, merging updates with existing Stage spec and validating DAG cycles.
kargo_apply_warehouse Write Create or update a Kargo Warehouse with Git, Image, or Helm Chart subscriptions.
kargo_approve_freight Write (destructive) Manually approve a Freight bundle (by SHA-1 name or alias) for promotion to a target Stage.
kargo_delete_resource Write (destructive) Delete a Kargo Stage, Warehouse, PromotionTask, ClusterPromotionTask, or ProjectConfig after confirmation.
kargo_diagnose_stage Read Diagnose a Kargo Stage by correlating conditions, Promotion step traces, Verification AnalysisRuns, holds, and events (N-to-1).
kargo_diagnose_warehouse Read Diagnose a Kargo Warehouse by inspecting artifact discovery status, conditions, and deprecated Kargo v1.9–v1.12 fields (N-to-1).
kargo_manage_credentials Write (destructive) Create, update, or delete Kargo repository credentials, generic secrets, or ConfigMaps without exposing secret values.
kargo_manage_freight Write (destructive) Update a Freight human-friendly alias, manually assemble a Freight item, or delete unused Freight.
kargo_manage_project Write (destructive) Create or delete a Kargo Project (cluster-scoped organizational boundary).
kargo_manage_promotion Write (destructive) Abort a running/pending Kargo Promotion or refresh (wake) a waiting Promotion.
kargo_manage_roles Write (destructive) Create or delete a managed Kargo Role, or grant/revoke OIDC user claims and stage permissions.
kargo_manage_verification Write (destructive) Re-run (reverify) or abort a Stage's verification AnalysisRun, or delete an AnalysisTemplate.
kargo_promote Write Promote Freight to a Stage (by SHA-1 name, alias, or origin Warehouse) or to all immediate downstream Stages.
kargo_query_freight Read Query and filter Kargo Freight bundles in a project by stage availability, origin Warehouse, or alias.
kargo_refresh Write Trigger immediate reconciliation or artifact discovery on a Warehouse, Stage, Promotion, ProjectConfig, or ClusterConfig.
kargo_rollback_stage Write (destructive) Roll back a Kargo Stage to a previous known-good Freight using Kargo's roll-forward promotion model (N-to-1).
kargo_trace_freight Read Trace a Freight bundle or versioned artifact across all Stages in a Kargo project (N-to-1).
All 18 resources
Resource What it returns
kargo://projects List all Kargo Projects with readiness status
kargo://server/capabilities Server write mode, enabled toolsets, Kargo API connectivity, and Kargo version
kargo://cluster-promotion-tasks/{task} Sanitized YAML manifest for a cluster-scoped ClusterPromotionTask
kargo://projects/{project} Project status and ProjectConfig (promotionPolicies, webhookReceivers, generated webhook URLs)
kargo://projects/{project}/analysis-runs/{run} Verification AnalysisRun status and metric results
kargo://projects/{project}/analysis-runs/{run}/logs Job-metric container logs for a verification AnalysisRun
kargo://projects/{project}/analysis-templates Project AnalysisTemplates and cluster-scoped ClusterAnalysisTemplates available for Stage verification
kargo://projects/{project}/credentials Redacted repository credentials, generic credentials, and ConfigMaps in a Kargo project (secret values are never exposed)
kargo://projects/{project}/events Recent Kubernetes Events in a Kargo project
kargo://projects/{project}/freight/{freight_or_alias} Detailed Freight bundle (SHA-1 id, alias, origin Warehouse, commits, images, charts, stage states)
kargo://projects/{project}/pipeline Complete pipeline DAG topology (Warehouses -> Stages), current Freight, health, auto-promotion, and holds
kargo://projects/{project}/promotion-tasks/{task} Sanitized YAML manifest for a project PromotionTask
kargo://projects/{project}/promotions Recent Promotions in a Kargo project with phase and timestamps
kargo://projects/{project}/promotions/{promotion} Detailed Promotion execution trace (phase, message, per-step status, timings, outputs)
kargo://projects/{project}/roles Kargo RBAC Roles, OIDC claim bindings, and permissions in a project
kargo://projects/{project}/stages/{stage} Concise Stage status (phase, health, currentFreight, verification, promotions, holds, conditions)
kargo://projects/{project}/stages/{stage}/manifest Sanitized YAML manifest for a Kargo Stage (strips managedFields and redacts literal env secrets)
kargo://projects/{project}/warehouses/{warehouse} Concise Warehouse status, subscriptions, lastFreightID, and discoveredArtifacts

Development

git clone https://github.com/talkops-ai/talkops-mcp.git
cd talkops-mcp/src/kargo-mcp-server
uv sync --dev
uv run pytest
uv run kargo-mcp-server --help

Get help

License

Apache 2.0. See LICENSE.

Metadata

Release files for talkops-kargo-mcp-server 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for talkops-kargo-mcp-server 0.2.1
File Size Uploaded Provenance Actions
talkops_kargo_mcp_server-0.2.1.tar.gz 217.7 kB With provenance Details for talkops_kargo_mcp_server-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for talkops-kargo-mcp-server 0.2.1
File Interpreter ABI Platform Actions
talkops_kargo_mcp_server-0.2.1-py3-none-any.whl Python 3 none any Details for talkops_kargo_mcp_server-0.2.1-py3-none-any.whl

Total release size: 308.7 kB

Release files / talkops_kargo_mcp_server-0.2.1.tar.gz

Download URL talkops_kargo_mcp_server-0.2.1.tar.gz
Size 217.7 kB
Tags Source
SHA-256 checksum
How to use checksums
6fa0baa836e13fc39443ad6db3bc2b8df503cbd4e66e661c93778c91a875e663
BLAKE2b-256 checksum
How to use checksums
7210a18c460cf9c9a00addb8a8b2e9c5954b3f71eaf50a486ae39c4da48204aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / talkops_kargo_mcp_server-0.2.1-py3-none-any.whl

Download URL talkops_kargo_mcp_server-0.2.1-py3-none-any.whl
Size 91.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
97b4e80b71eb68ec194b81896ce8e85d86d6a2fd117493b9840d46c105c92f5c
BLAKE2b-256 checksum
How to use checksums
28052e3a7e452ec9e7b2d07a0a0c6f352f18e1bb0b3eedf98cf8dc65665b2f01
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for talkops-kargo-mcp-server 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for talkops_kargo_mcp_server-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page