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.
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:
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
guestbookproject. What's running in each stage?" - "Promote the latest freight to
staging." - "Why did the last promotion to
prodfail?"
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.