harbor-registry-mcp

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.

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 bulk cleanup (harbor_delete_old_artifacts(dry_run=True)) — the agent must flip it 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
• 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

... View full README on GitHub