harbor-registry-mcp
harbor-registry-mcp
MCP-сервер для Harbor Registry. Позволяет LLM-агенту (Claude Code, Cursor, OpenCode и др.) просматривать проекты, репозитории и артефакты, создавать отчеты о хранилище, находить кандидатов на очистку и удалять артефакты без тегов или устаревшие артефакты — и все это с защитными механизмами (по умолчанию включен «сухой прогон» (dry-run) для массового удаления).
Python, FastMCP, транспорт stdio.
Работает с любым экземпляром Harbor 2.x — SaaS или self-hosted / on-prem.
Почему еще один Harbor MCP?
Существует пара сообществ Harbor MCP (nomagicln/mcp-harbor, bupd/harbor-mcp-server), но они предоставляют только базовые эндпоинты для листинга/получения данных. Этот сервер добавляет отчеты о хранилище, кандидатов на очистку, удаление артефактов без тегов и удаление старых артефактов с возможностью «сухого прогона» — операции, которые действительно нужны DevOps-инженерам для освобождения дискового пространства.
Related MCP server: Harbor MCP Server
Особенности проектирования
Аннотации инструментов — инструменты только для чтения имеют
readOnlyHint: True; деструктивные инструменты (harbor_delete_*) имеютdestructiveHint: True, поэтому MCP-клиенты запрашивают подтверждение.«Сухой прогон» по умолчанию при массовой очистке (
harbor_delete_old_artifacts(dry_run=True)) — агент должен изменить этот параметр для выполнения.Структурированный вывод — каждый инструмент возвращает типизированный объект (TypedDict) + сводку в формате markdown.
Структурированные ошибки — коды 401 / 403 / 404 / 429 / 5xx сопоставлены с полезными подсказками.
Валидация входных данных Pydantic для каждого аргумента.
Снимок уязвимостей —
harbor_list_artifactsотображает статус сканирования и количество уязвимостей, если включен параметрwith_scan_overview.
Функции (8 инструментов)
Обнаружение и инспекция
harbor_list_projects— проекты с количеством репозиториев и видимостьюharbor_list_repos— репозитории в проектеharbor_list_artifacts— артефакты в репозитории с тегами/размером/статусом сканированияharbor_storage_report— полный отчет по хранилищу проекта (все репозитории × все артефакты)
Планирование очистки
harbor_cleanup_candidates— предложения по удалению (без тегов, никогда не скачивались, старые версии)
Выполнение очистки (деструктивные)
harbor_delete_artifact— удаление одного артефакта по тегу или дайджестуharbor_delete_untagged— удаление всех артефактов без тегов в проекте/репозиторииharbor_delete_old_artifacts— сохранение N последних версий в репозитории, удаление остальных (по умолчанию «сухой прогон»)
Установка
Требуется Python 3.10+.
# via uvx (recommended)
uvx --from harbor-registry-mcp harbor-registry-mcp
# or via pipx
pipx install harbor-registry-mcpКонфигурация
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Или в .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"
}
}
}
}Проверка:
claude mcp list
# harbor: uvx --from harbor-registry-mcp harbor-registry-mcp - ✓ ConnectedПеременные окружения
Переменная | Обязательно | Описание |
| да | URL Harbor (без слеша в конце) |
| да | Имя пользователя Harbor — рекомендуется использовать робот-аккаунт |
| да | Пароль или токен робота |
| нет |
|
Пример использования
"Отчет о хранилище для проекта
einvy-pub""Найти кандидатов на очистку в
qa-assistant— оставить 3 последних""Удалить все артефакты без тегов в
qa-assistant""Удалить старые артефакты в
qa-assistant/pgvector-ragв режиме сухого прогона, оставить 1 последний""Что находится в
einvy-pub/my-image?"
Безопасность
Инструменты чтения используют
readOnlyHint: True— подтверждение не требуется.Инструменты удаления используют
destructiveHint: True— клиенты должны запрашивать подтверждение.harbor_delete_old_artifactsпо умолчанию имеетdry_run=True; агент должен явно установитьdry_run=Falseдля фактического удаления.harbor_cleanup_candidatesработает только для чтения — он только предлагает кандидатов, но никогда не удаляет их.
Разработка
git clone https://github.com/mshegolev/harbor-registry-mcp.git
cd harbor-registry-mcp
pip install -e '.[dev]'
pytestЛицензия
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