harbor-registry-mcp
This server lets LLM agents manage Harbor registries via MCP tools: inspect projects/repositories/artifacts, generate storage reports, plan cleanup, and safely execute deletions.
Discovery & inspection
List all Harbor projects with repository counts, visibility, and pagination.
List repositories within a project, including artifact and pull counts.
List artifacts in a repository with tags, digest, size, push/pull timestamps, and vulnerability scan status.
Storage monitoring
Generate a project storage report breaking down usage by repository and artifact, sorted by size.
Cleanup planning
Identify cleanup candidates (untagged/orphaned, never-pulled, or old versions beyond a keep-N count) without deleting anything.
Cleanup execution
Delete a single artifact by tag or digest.
Delete all untagged artifacts in a project or a specific repository.
Delete old artifacts while keeping the N newest versions in a repository.
Safety features
Read-only tools are marked with
readOnlyHint; destructive tools carrydestructiveHintfor confirmation prompts.Bulk deletions default to dry-run mode and require explicit
dry_run=Falseto actually delete.Includes Pydantic input validation, structured output, and detailed error messages.
Provides tools for managing Harbor registry, including listing projects, repositories, and artifacts, generating storage reports, identifying cleanup candidates, and deleting untagged or old artifacts with dry-run support.
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.
Related MCP server: Harbor MCP Server
Design highlights
Tool annotations — read-only tools get
readOnlyHint: True; destructive ones (harbor_delete_*) carrydestructiveHint: Trueso MCP clients ask for confirmation.Dry-run by default on both bulk cleanups (
harbor_delete_untagged,harbor_delete_old_artifacts) — the agent must passdry_run=Falseto 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_artifactssurfaces scan status and counts ifwith_scan_overviewis enabled.
Features (8 tools)
Discovery & inspection
harbor_list_projects— projects with repo counts and visibilityharbor_list_repos— repositories in a projectharbor_list_artifacts— artifacts in a repository with tags/size/scan statusharbor_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 digestharbor_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-mcpConfiguration
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-mcpOr 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 - ✓ ConnectedEnvironment variables
Variable | Required | Description |
| yes | Harbor URL (no trailing slash) |
| yes | Harbor username — robot account recommended |
| yes | Password or robot token |
| no |
|
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_untaggedandharbor_delete_old_artifactsboth default todry_run=True; the agent must explicitly setdry_run=Falseto actually delete.harbor_cleanup_candidatesis 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]'
pytestLicense
MIT © Mikhail Shchegolev
Available Tools
8 toolsharbor_cleanup_candidatesARead-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_artifactADestructive
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_artifactsADestructive
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_untaggedADestructiveIdempotent
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_artifactsARead-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_projectsARead-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_reposARead-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_reportARead-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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Unofficial Docker Hub MCP — wraps the Docker Hub v2 API (free, no auth required for public data)
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
Toggl 2.0 MCP server for tasks, projects, time entries, and workspace operations.
MCP server for LingoHub — localization projects, resources, exports and repository pushes.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceA 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 npm7MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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.6MIT
- AlicenseNot gradedqualityDmaintenanceMCP Harbor is a Node.js application that provides a Model Context Protocol (MCP) server for interacting with Harbor container registry.MIT
- AlicenseNot gradedqualityCmaintenanceEnables interacting with a Harbor container registry through the Model Context Protocol, supporting operations for projects, repositories, tags, and Helm charts.1MIT