Skip to main content
Glama
harbor-registry-mcp

harbor-registry-mcp

harbor-registry-mcp

PyPI Python License: MIT

MCP server for Harbor Registry. Lets an LLM agent (Claude Code, Cursor, OpenCode, etc.) list projects, repositories and artifacts, run storage reports, find cleanup candidates, and delete untagged or old artifacts — all with safety rails (dry-run by default for bulk delete).

Python, FastMCP, stdio transport.

Works with any Harbor 2.x instance — SaaS or self-hosted / on-prem.

Why another Harbor MCP?

A couple of community Harbor MCPs exist (nomagicln/mcp-harbor, bupd/harbor-mcp-server) but they expose only the basic list/get endpoints. This one adds storage reports, cleanup candidates, delete untagged, and delete old artifacts with dry-run — the operations DevOps engineers actually need to reclaim disk space.

Related MCP server: Harbor MCP Server

Design highlights

  • Tool annotations — read-only tools get readOnlyHint: True; destructive ones (harbor_delete_*) carry destructiveHint: True so MCP clients ask for confirmation.

  • Dry-run by default on both bulk cleanups (harbor_delete_untagged, harbor_delete_old_artifacts) — the agent must pass dry_run=False to execute.

  • Structured output — every tool returns a typed payload (TypedDict) + a markdown summary.

  • Structured errors — 401 / 403 / 404 / 429 / 5xx mapped to actionable hints.

  • Pydantic input validation for every argument.

  • Vulnerability snapshot — harbor_list_artifacts surfaces scan status and counts if with_scan_overview is enabled.

Features (8 tools)

Discovery & inspection

  • harbor_list_projects — projects with repo counts and visibility

  • harbor_list_repos — repositories in a project

  • harbor_list_artifacts — artifacts in a repository with tags/size/scan status

  • harbor_storage_report — full project storage breakdown (all repos × all artifacts)

Cleanup planning

  • harbor_cleanup_candidates — suggest what to delete (untagged, never-pulled, old versions)

Cleanup execution (destructive)

  • harbor_delete_artifact — delete a single artifact by tag or digest

  • harbor_delete_untagged — delete all untagged artifacts in a project/repo (dry-run default)

  • harbor_delete_old_artifacts — keep N latest per repo, delete the rest (dry-run default)

Installation

Requires Python 3.10+.

# via uvx (recommended)
uvx --from harbor-registry-mcp harbor-registry-mcp

# or via pipx
pipx install harbor-registry-mcp

Configuration

claude mcp add harbor -s project \
  --env HARBOR_URL=https://harbor.example.com \
  --env HARBOR_USERNAME='robot$your-robot' \
  --env HARBOR_PASSWORD=your-robot-token \
  --env HARBOR_SSL_VERIFY=true \
  -- uvx --from harbor-registry-mcp harbor-registry-mcp

Or in .mcp.json:

{
  "mcpServers": {
    "harbor": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "harbor-registry-mcp", "harbor-registry-mcp"],
      "env": {
        "HARBOR_URL": "https://harbor.example.com",
        "HARBOR_USERNAME": "robot$your-robot",
        "HARBOR_PASSWORD": "${HARBOR_PASSWORD}",
        "HARBOR_SSL_VERIFY": "true"
      }
    }
  }
}

Check:

claude mcp list
# harbor: uvx --from harbor-registry-mcp harbor-registry-mcp - ✓ Connected

Environment variables

Variable

Required

Description

HARBOR_URL

yes

Harbor URL (no trailing slash)

HARBOR_USERNAME

yes

Harbor username — robot account recommended

HARBOR_PASSWORD

yes

Password or robot token

HARBOR_SSL_VERIFY

no

true/false. Default: true.

Example usage

  • "Storage report for project einvy-pub"

  • "Find cleanup candidates in qa-assistant — keep latest 3"

  • "Delete all untagged artifacts in qa-assistant"

  • "Dry-run delete of old artifacts in qa-assistant/pgvector-rag, keep 1 latest"

  • "What's in einvy-pub/my-image?"

Safety

  • Read tools use readOnlyHint: True — no confirmation needed.

  • Delete tools use destructiveHint: True — clients should confirm.

  • harbor_delete_untagged and harbor_delete_old_artifacts both default to dry_run=True; the agent must explicitly set dry_run=False to actually delete.

  • harbor_cleanup_candidates is read-only — it only suggests candidates, never deletes.

Development

git clone https://github.com/mshegolev/harbor-registry-mcp.git
cd harbor-registry-mcp
pip install -e '.[dev]'
pytest

License

MIT © Mikhail Shchegolev

Available Tools

8 tools
harbor_cleanup_candidatesA
Read-onlyIdempotent

Suggest which artifacts could be deleted to reclaim space.

READ-ONLY — never deletes anything; just produces a list with reasons. Use harbor_delete_artifact / harbor_delete_untagged / harbor_delete_old_artifacts to act on the results.

Reasons emitted: - untagged — artifact has no tags (orphaned layer) - never_pulled — artifact has never been pulled (and is past the keep_latest_per_repo cutoff) - old_version — artifact is older than the keep_latest_per_repo newest tagged artifacts

Inputs: project_name (required), include_untagged, include_zero_pulls, keep_latest_per_repo. Returns: project, candidates_count, total_reclaimable, total_reclaimable_bytes, +2 more

harbor_delete_artifactA
Destructive

Delete a single artifact by tag or digest.

DESTRUCTIVE & IRREVERSIBLE — Harbor immediately removes the manifest from its catalogue; the underlying blobs are reclaimed by the next GC sweep. There is no soft-delete or undo.

Returns the freed space and tag list for confirmation.

Inputs: project_name (required), repository_name (required), reference (required). Returns: success, project, repository, reference, +4 more

harbor_delete_old_artifactsA
Destructive

Keep the N newest artifacts in a repository, delete the rest.

DESTRUCTIVE. dry_run=True is the default — the agent must explicitly set dry_run=False to actually delete. Each entry in to_delete carries a deleted field (True/False after real run, None in dry-run).

Inputs: project_name (required), repository_name (required), keep_count, dry_run. Returns: project, repository, dry_run, keeping, +6 more

harbor_delete_untaggedA
DestructiveIdempotent

Delete all untagged artifacts in a project (or single repository).

DESTRUCTIVE. Untagged artifacts are typically orphaned layers left behind after pushing a new tag of the same image — generally safe to delete. The full project sweep is opaque, so the response includes repos_scanned for visibility.

Inputs: project_name (required), repository_name. Returns: project, repos_scanned, deleted_count, freed_size, +3 more

harbor_list_artifactsA
Read-onlyIdempotent

List artifacts (tags) in a repository, newest first.

Each artifact carries digest, size, push/pull timestamps, scan status and vulnerability counts (if scanned).

Pagination: if has_more is True, call again with page + 1. For repositories with hundreds of artifacts prefer harbor_storage_report or harbor_cleanup_candidates which paginate internally.

Inputs: project_name (required), repository_name (required), page, page_size. Returns: project, repository, total_size, total_size_bytes, +6 more

harbor_list_projectsA
Read-onlyIdempotent

List Harbor projects, sorted by repository count (descending within the page).

Use this first to discover which Harbor projects exist before drilling in with harbor_list_repos / harbor_list_artifacts.

Pagination: if has_more is True, call again with page + 1. Note that sorting is per-page — agents that need a global ranking should aggregate across pages.

Returns: dict with keys projects_count / page / page_size / has_more / next_page / projects (list).

Inputs: page, page_size. Returns: projects_count, page, page_size, has_more, +2 more

harbor_list_reposA
Read-onlyIdempotent

List repositories in a Harbor project.

Each repository is reported with artifact count and total pull count (useful for spotting unused repos before cleanup).

Pagination: if has_more is True, call again with page + 1.

Inputs: project_name (required), page, page_size. Returns: project, repositories_count, page, page_size, +3 more

harbor_storage_reportA
Read-onlyIdempotent

Full storage breakdown for a Harbor project.

Iterates every repository × every artifact and returns a sorted-by-size report — the canonical view for "what's eating up our quota?". Performs O(repos × artifacts) API calls; emits progress events through MCP Context.

Inputs: project_name (required). Returns: project, total_repositories, total_size, total_size_bytes, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct operation: listing, reporting, or deleting. The cleanup candidate tool is clearly separate from the delete tools, and deletion tools are differentiated by scope (single, old, untagged). No overlapping purposes.

    Naming Consistency4/5

    Most tools follow the harbor_verb_noun pattern (e.g., harbor_delete_artifact, harbor_list_projects), but harbor_storage_report uses a noun_noun pattern, breaking consistency. The prefix and general style are otherwise uniform.

    Tool Count5/5

    Eight tools cover the essential operations for a Harbor registry: discovery (list projects, repos, artifacts), cleanup (candidates, delete single, delete old, delete untagged), and reporting (storage report). The count is well-scoped without being excessive.

    Completeness5/5

    The tool set provides comprehensive coverage for registry management: full lifecycle for artifacts (list, delete individual/bulk/untagged), project and repository exploration, storage analysis, and a cleanup candidate suggestion tool. No major gaps in functionality for the intended domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      A Node.js application that provides a Model Context Protocol server for interacting with Harbor container registry, supporting operations for projects, repositories, tags, and Helm charts.
      21 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI models to interact with Harbor container registries to manage projects, repositories, and system configurations in real time. It provides a suite of tools for monitoring health, retrieving statistics, and performing searches across registry data.
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP Harbor is a Node.js application that provides a Model Context Protocol (MCP) server for interacting with Harbor container registry.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables interacting with a Harbor container registry through the Model Context Protocol, supporting operations for projects, repositories, tags, and Helm charts.
      1
      MIT