Skip to main content
Glama
harbor-registry-mcp

harbor-registry-mcp

harbor-registry-mcp

PyPI Python License: MIT

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

Переменные окружения

Переменная

Обязательно

Описание

HARBOR_URL

да

URL Harbor (без слеша в конце)

HARBOR_USERNAME

да

Имя пользователя Harbor — рекомендуется использовать робот-аккаунт

HARBOR_PASSWORD

да

Пароль или токен робота

HARBOR_SSL_VERIFY

нет

true/false. По умолчанию: true.

Пример использования

  • "Отчет о хранилище для проекта 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 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