harbor-mcp
Connects to a self-hosted Harbor v2.16.0 REST API, exposing tools for system status and search, project and membership management, repositories, artifacts, tags, labels, vulnerability scans, robot accounts, and garbage-collection schedules, with guarded write operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@harbor-mcp list all repositories in the library project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
harbor-mcp
MCP connector for a self-hosted Harbor v2.16.0 REST API. It speaks official /api/v2.0 JSON over stdio and over stateless Streamable HTTP on localhost.
Harbor is Apache-2.0 software (LICENSE in the v2.16.0 source tree). This connector is MIT. It does not copy Harbor source. It is not affiliated with goharbor/harbor.
spec/api-inventory.json is a compact extraction of every /api/v2.0 operation in v2.16.0 api/v2.0/swagger.yaml. It records the release version, Apache-2.0, file sha256s, and routeTreeSha256. scripts/gen-operations.mjs maps that inventory onto tool actions or exclusions and writes src/operations.ts and harbor.routes.json. A route that is neither mapped nor excluded fails generation. Do not edit src/operations.ts by hand. Default generation and npm run ci read only the committed inventory.
HARBOR_URL, HARBOR_USERNAME, and HARBOR_PASSWORD (or HARBOR_PASSWORD_FILE) are required. There is no default origin. The connector does not start Harbor. Each request sends Authorization: Basic. Credentials are never placed in the URL. Robot accounts use the same Basic auth with a username such as robot$project+name.
Setup
npm install
npm run ci
npm start
npm run start:httpnpm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.
{
"mcpServers": {
"harbor": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"HARBOR_URL": "http://127.0.0.1:18080",
"HARBOR_USERNAME": "admin",
"HARBOR_PASSWORD": "...",
"HARBOR_ALLOW_WRITES": "false"
}
}
}
}The password is a Harbor user password or a robot secret. The connector never prints it.
HTTP mode has no authentication of its own. Keep it on localhost. Do not put secrets in a Docker image.
docker build -t harbor-mcp .
docker run -p 127.0.0.1:3000:3000 \
-e HARBOR_URL=http://127.0.0.1:18080 \
-e HARBOR_USERNAME=admin \
-e HARBOR_PASSWORD=... \
harbor-mcpRegenerate the registry from the committed inventory.
npm run gen:operations
node scripts/gen-operations.mjs --checkRefresh the inventory from an official v2.16.0 tree. This is the only command that reads route source. Keep that tree outside this MIT connector (for example /workspace/tools/harbor/upstream).
node scripts/gen-operations.mjs --source-root /path/to/harbor --write-inventory
node scripts/gen-operations.mjs --source-root /path/to/harbor --checkHARBOR_SOURCE_ROOT is accepted by a write run. --check ignores that variable unless you also pass --source-root.
scripts/live-check.mjs talks to a real server over stdio. Set HARBOR_URL. Set HARBOR_USERNAME. Set HARBOR_PASSWORD or HARBOR_PASSWORD_FILE to a chmod 600 file outside this repo. The script unsets DATABASE_URL. It prints pass or fail lines only, and it redacts passwords and live robot secrets. It does not run inside npm run ci. A missing password is a failure.
Isolated local runtime scripts live under /workspace/tools/harbor (start.sh, stop.sh). They keep Postgres data and secrets under /tmp/harbor-mcp.
Related MCP server: dockhand-readonly-mcp
Config
Variable | Meaning |
| Required. Origin only, |
| Required. Harbor user or robot account ( |
| Required unless |
| Optional. chmod 600 file whose trimmed contents are the password. Used when |
| Must be the literal |
| Local request budget. Default 30. Cache hits do not spend it. Live-check sets 600. |
| Upstream timeout. Default 20000. |
| Read cache TTL. Default 60. Writes clear the cache. |
| Contact token in the User-Agent. Must not contain the password. |
|
|
| HTTP port. Default 3000. |
Invalid values are reported by field name and issue code. The rejected value is not included.
Calls go to /api/v2.0/... paths from the operations registry. Accept is application/json. JSON writes send Content-Type: application/json. Redirects are refused so credentials are not forwarded. There are no automatic retries, including HTTP 429. Credentials are never placed in the URL, query, or User-Agent.
Harbor CSRF tokens are not sent. Harbor's Basic-auth API does not require them.
Repository names that contain a slash (nested OCI names) are double-URL-encoded (team/app becomes team%252Fapp) the way Harbor's API expects. Digest references are encoded once (sha256:abc becomes sha256%3Aabc). harbor_artifacts get and list accept with_label. Harbor omits labels unless that flag is true.
Safety
Reads run without a write flag. A write is sent only when confirm is the boolean true and HARBOR_ALLOW_WRITES=true. That gate covers every mutation in the registry: project create/update/delete, member add/update/remove, metadata writes, repository update/delete, artifact delete, tag create/delete, artifact label add/remove, scan trigger, robot create/update/refresh/delete, label create/update/delete, and GC schedule create/update. Omit confirm, or pass boolean false, and the tool returns a dry-run preview of method, path, query, and body. It sends nothing. blocked is false on that preview, whether or not writes are enabled. confirm: true with writes disabled returns the same preview with blocked true and the reason HARBOR_ALLOW_WRITES is not true. The write was not sent. The string "true" is rejected.
Omitted fields are dropped. public: false and timeout: 0 are sent when you set them. A field that is not valid for the selected action is rejected before any request is sent. Unknown fields are rejected.
HTTP 401 is unauthorized. HTTP 403 is forbidden. HTTP 400 and 422 are invalid input. HTTP 404 is not found. HTTP 409 is conflict. HTTP 429 includes Retry-After when the header is present. Other failures are server, network, or timeout. Response bodies are capped at 1,000,000 bytes.
Every non-empty string or number under a sensitive key on that request is a secret, at any nesting depth and inside arrays or objects below that key, including 1-character values and values longer than 64 characters. Sensitive keys include secret, token, password, authorization, apiKey/apikey, session, cookie, credential, passphrase, privateKey, value, and similar names. The configured password (substring-masked at length 8 or more) and any URL userinfo found in the request are included too. Secrets are collected once per request and are not kept for the next call.
Sensitive-key values become [redacted] in objects. Substring masking of free text (raw, percent-encoded any-case hex, and JSON-escaped forms) runs only for secrets of length 8 or more. If the request carries a shorter credential, upstream free-text error bodies and log detail are replaced with upstream detail omitted because this request carried a short credential. Object keys and this connector's preview envelope (method, path, summary, executed, and the other write-gate fields) are not rewritten. That rule covers MCP success results, MCP error text, write previews, HTTP and network errors, and every logger line.
Robot create and refresh_secret return the new secret once in the structured tool result so the caller can store it. That value is never written to logs. Previews redact it. Later reads of the same robot do not include the secret.
Tools
Six tools. Each takes action plus the fields for that action. Fields for a different action are rejected.
Tool | Actions | Routes |
| health, ping, search, statistics, systeminfo, volumes, current_user, current_permissions | GET |
| list, create, get, update, delete, deletable, summary, members_list, members_add, member_get, member_update, member_remove, metadata_list, metadata_add, metadata_get, metadata_update, metadata_delete |
|
| list, list_all, get, update, delete |
|
| list, get, delete, tags_list, tag_create, tag_delete, label_add, label_remove, vulns, scan, accessories | artifact, tag, label, scan, and vulnerability addition paths |
| list, create, get, update, refresh_secret, delete |
|
| quotas_list, quota_get, labels_list, label_create, label_get, label_update, label_delete, gc_schedule, gc_history, gc_schedule_create, gc_schedule_update, retention_metadata, retention_get, webhook_list, webhook_events | quotas, labels, GC schedule/history, retention get, webhook list/events |
Writes need document for JSON bodies (project create, member add, robot create, label create, GC schedule, metadata, repository update). Tag create uses name.
62 of 208 v2.16.0 /api/v2.0 operations are mapped. 146 are excluded. The registry has 62 actions. See harbor.routes.json for every mapping and exclusion reason.
Coverage and exclusions
In scope: health/ping/search/statistics/systeminfo/volumes, current user and permissions, project CRUD plus members and metadata, repository list/get/update/delete, artifact list/get/delete, tags, artifact labels, vulnerability addition, scan trigger, accessories, robot CRUD and secret refresh, quotas read, labels CRUD, GC schedule read/create/update and history, retention metadata and get, webhook policy list and event types.
Excluded with a stored reason, grouped:
User directory, password, CLI secret, and sysadmin writes (
/usersexcept current user).LDAP and OIDC administration.
System configuration get/update (
/configurations,/internalconfig) because they expose and write instance secrets.Replication registries, policies, and executions (remote credentials).
Scanner registration and per-project scanner assignment.
P2P preheat instances and policies.
Immutable tag rules, webhook writes/executions, user groups, RBAC role catalog.
Raw icon binaries and certificate download.
Jobservice worker/queue admin, audit log listing, CVE export, security hub, scan-all schedules.
Quota writes. Retention policy writes and executions.
Copy-artifact, scan-stop, report logs, and generic artifact additions.
There is no arbitrary HTTP method/path passthrough.
Source provenance
Official latest stable release checked 12 Nov 2026: v2.16.0 (released 10 Nov 2026), Apache-2.0. Inventory from api/v2.0/swagger.yaml at tag v2.16.0.
Pinned inventory hashes:
File | sha256 |
|
|
route tree |
|
A copy of the swagger file and Harbor LICENSE is stored under /workspace/tools/harbor/upstream for --source-root checks. Public CI runs offline from spec/api-inventory.json.
Other MCP servers
Read 12 Nov 2026 from GitHub API and raw files. Evidence: /workspace/tools/harbor/rivals/EVIDENCE.md.
Server | Writes | Confirmation | Notes |
nomagicln/mcp-harbor (11 tools, MIT, TS, archived 1 Apr 2025, 7 stars) | 5: create/delete project, delete repository/tag/chart | None. Delete schemas have no | Sets |
bupd/harbor-mcp-server (12 tools on | 1: | Tool argument | HTTP Basic via |
Honest differences that still hold after those reads:
Every mutation, including scan, GC schedule, robot create/refresh, tag create/delete, and project delete, needs boolean
confirm: trueandHARBOR_ALLOW_WRITES=true.Omitted or false
confirmalways returns a method/path/query/body preview with zero HTTP writes. Robot secrets in that preview are[redacted].nomagicln has unconfirmed deletes and disables TLS verification. This connector does not disable TLS and does not send deletes without the two-key gate.
bupd confirms only system configuration update, and that tool is excluded here because it writes instance secrets. bupd has no project/repo/tag deletes.
Request-scoped redaction includes robot
secret, passwords, registry credentials, percent-encoded any-case forms, and JSON-escaped forms. Nothing accumulates across requests.Route coverage is checked by the generator against a committed independent inventory. Public CI is offline.
Six action-field toolsets instead of one tool per route.
No automatic retries. Redirects are refused.
If a later rival adds the same two-key gate and dry-run preview on every write, that would no longer be unique.
Limitations
User, LDAP, OIDC, system config, replication, scanner, and P2P admin stay out of the tool list. Use Harbor's own UI if you need those.
Isolated live stack runs Harbor core, Postgres, Redis, distribution registry, and registryctl on loopback. Portal and jobservice are not started. Scan trigger and GC execution stay unverified. See
LIVE-CHECK.md.Robot secrets appear once in the create/refresh tool result. Store them immediately. They are never logged.
Live bad passwords from v2.16.0 are recorded in
LIVE-CHECK.md. Unit tests still simulate 401, 403, 404, 422, and 429 with one fetch. Live-check does not force HTTP 429.The connector never starts or stops the user's Harbor. Isolated live scripts under
/workspace/tools/harborare throwaway only.A short credential (under 8 characters) that is spelled the same as an object key or a word in this connector's own preview envelope still appears there as that key or word. Values that contain it are redacted, and upstream free text is replaced. Use credentials of 8 or more characters.
Live check
See LIVE-CHECK.md for the checks that actually ran, including the first core-only run and the later registry run. npm run live-check is not part of npm run ci. Set HARBOR_TOOLS_DIR to the directory that contains bin/crane (or set HARBOR_CRANE to the binary) so the live script can push one OCI image.
npm run ci typechecks, lints, tests, and builds. node scripts/gen-operations.mjs --check reports 62 mapped routes, 146 excluded, 62 tool actions, and 208 spec routes.
Run unset DATABASE_URL, set HARBOR_URL, HARBOR_USERNAME, and HARBOR_PASSWORD or HARBOR_PASSWORD_FILE. Then run npm run live-check. The script never prints the password.
License
MIT. Harbor itself is Apache-2.0. This connector only talks to the published REST API.
Available Tools
6 toolsharbor_adminBDestructive
Quotas, labels, GC schedule and history, retention metadata, and webhook policy list. GC schedule writes and label writes are gated. Writes run only when confirm is true and HARBOR_ALLOW_WRITES=true. Actions: quotas_list, quota_get, labels_list, label_create, label_get, label_update, label_delete, gc_schedule, gc_history, gc_schedule_create, gc_schedule_update, retention_metadata, retention_get, webhook_list, webhook_events.
Inputs: action (required), id, name, page, +6 more.
harbor_artifactsBDestructive
Artifact list and get, tags, artifact labels, vulnerability addition, scan trigger, and delete. Writes run only when confirm is true and HARBOR_ALLOW_WRITES=true. Actions: list, get, delete, tags_list, tag_create, tag_delete, label_add, label_remove, vulns, scan, accessories.
Inputs: action (required), name, page, confirm, +10 more.
harbor_projectsBDestructive
Project list, get, summary, create, update, delete, members, and metadata. Writes run only when confirm is true and HARBOR_ALLOW_WRITES=true. Actions: list, create, get, update, delete, deletable, summary, members_list, members_add, member_get, member_update, member_remove, metadata_list, metadata_add, metadata_get, metadata_update, metadata_delete.
Inputs: action (required), mid, name, page, +9 more.
harbor_repositoriesADestructive
Repository list, get, description update, and delete. Repository names with slashes are double-URL-encoded. Writes run only when confirm is true and HARBOR_ALLOW_WRITES=true. Actions: list, list_all, get, update, delete.
Inputs: action (required), q, page, confirm, +4 more.
harbor_robotsADestructive
Robot account list, get, create, update, secret refresh, and delete. Create and refresh return secret once in the tool result and never in logs. Writes run only when confirm is true and HARBOR_ALLOW_WRITES=true. Actions: list, create, get, update, refresh_secret, delete.
Inputs: action (required), q, page, confirm, +3 more.
harbor_systemCRead-only
Harbor health, ping, search, statistics, systeminfo, volumes, and the current user. Writes run only when confirm is true and HARBOR_ALLOW_WRITES=true. Actions: health, ping, search, statistics, systeminfo, volumes, current_user, current_permissions.
Inputs: action (required), q, page, scope, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The six tools are cleanly split by Harbor domain: system, projects, repositories, artifacts, robots, and admin. There is minor potential overlap around labels and metadata, since artifact labels, project metadata, and global admin labels live in different tools, but the descriptions make the intended boundaries clear.
All tool names follow a consistent harbor_<domain> convention, and action names within each tool use snake_case. The pattern is predictable despite grouping multiple actions under each domain tool.
Six domain-oriented tools are a well-scoped surface for a broad Harbor server. Each tool corresponds to a meaningful resource area, and the high action count inside tools like projects/admin is a dispatch design choice rather than excessive top-level tool count.
Core Harbor resource workflows are covered: projects, repositories, artifacts, robots, and several admin functions. However, there are notable gaps in admin operations, including webhook CRUD beyond list/events, user management, replication, audit logs, and full quota/retention management.
Maintenance
Related MCP Connectors
Unofficial Docker Hub MCP — wraps the Docker Hub v2 API (free, no auth required for public data)
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Streamable HTTP MCP gateway for NV oOS fleets — one API key, namespaced tools, quotas and policy.
Related MCP Servers
- AlicenseAqualityDmaintenanceCP server for Harbor Registry — projects, repositories, artifacts, storage reports, cleanup candidates. Works with any Harbor 2.x instance.846 PyPI1MIT
- FlicenseAqualityDmaintenanceRead-only MCP adapter for the Dockhand REST API, enabling secure querying of container environments, networks, stacks, and runtime status via STDIO or authenticated HTTP.81-
- AlicenseNot gradedqualityCmaintenanceEnables interacting with a Harbor container registry through the Model Context Protocol, supporting operations for projects, repositories, tags, and Helm charts.21 npm1MIT
- AlicenseAqualityCmaintenanceConnects MCP clients to a self-hosted photo library through its REST API, exposing assets, albums, people, search, and optional administrative toolsets with read-only defaults and confirm-gated writes. It supports stdio and localhost Streamable HTTP transports.5MIT