Dockerhub Api

CLI or API | MCP

Version: 1.3.4

Documentation — Installation, deployment, usage across the API, CLI, and MCP Docker Hub platform are maintained in docs/.

Table of Contents

• Overview
• Key Features
• Installation
• Usage
  • Python API / CLI
  • MCP
  • Agent (A2A)
• Environment Variables
• Deployment
• Safety Model
• Concepts
• License

Overview

Dockerhub Api is a production-grade Agent and Model Context Protocol (MCP) server that wraps the official Docker Hub API v2 (https://hub.docker.com): repositories and tags, immutable tags, personal and organization access tokens, organization members/settings/invites, teams, audit logs, and SCIM 2.0 provisioning — plus the Registry HTTP API v2 (registry-1.docker.io: manifests, blobs, digests, multi-arch inspection, OCI referrers, and gated push/remove) and Docker Scout (api.scout.docker.com: CVE/SBOM/policy intelligence).

Key Features

• Consolidated Action-Routed MCP Tools: Nine togglable tool modules (hub_auth, hub_repos, hub_org, hub_teams, hub_audit, hub_scim, hub_admin, hub_registry, hub_scout) minimize token overhead in LLM contexts.
• Three API surfaces, one package: the Hub management API, the Registry v2 image API (its own host + per-repository scoped-token auth), and Docker Scout — each with the same uniform envelope, redaction, and gating.
• JWT Auth Lifecycle: Short-lived bearer minted from POST /v2/auth/token (password, PAT dckr_pat_*, or org access token), cached and refreshed before expiry, with one transparent re-mint on 401.
• Rate-Limit Telemetry: X-RateLimit-* headers surfaced in every result; HTTP 429 retried with bounded Retry-After backoff.
• Safety by Default: Removes and org-settings writes are gated behind DOCKERHUB_ALLOW_DESTRUCTIVE (default False); secrets are redacted from tool results (plaintext tokens appear exactly once — on creation). Repository creation stays enabled: it is the primary release-provisioning use case.
• Integrated Graph Agent: Built-in Pydantic AI agent (dockerhub-agent) with A2A and AG-UI web interfaces.
• Native Telemetry & Tracing: Out-of-the-box OpenTelemetry exports and Langfuse tracing via agent-connector-sdk.

Installation

pip install dockerhub-api            # API client only
pip install "dockerhub-api[mcp]"     # + MCP server
pip install "dockerhub-api[all]"     # everything

# Connector-focused MCP server (includes the shared graph engine)
uv pip install "dockerhub-api[mcp]"

# Agent runtime (adds model orchestration to the shared graph engine)

# Everything (development)
uv pip install "dockerhub-api[all]"      # or: python -m pip install "dockerhub-api[all]"

Container images (:mcp)

One multi-stage docker/Dockerfile builds the MCP-only image (--target mcp):

docker build --target mcp   -t example/dockerhub-api:mcp    docker/   # connector-focused MCP server

agent (immutable agent digest) with a co-located :mcp sidecar.

Knowledge-graph database (epistemic-graph)

Agent Connector SDK core dependency (epistemic-graph[full]). The [mcp] extra keeps deployments can use the bundled engine. For production or shared state, run epistemic-graph as a dedicated database service and configure the runtime to use it. Deployment recipes (single-node + Raft HA), connection configuration, and architecture diagrams are documented in the epistemic-graph deployment guide.

Usage

Python API / CLI

from dockerhub_api.auth import get_client

api = get_client()  # reads DOCKERHUB_URL / DOCKER_HUB_USER / DOCKER_HUB_TOKEN

repos = api.get_repositories(namespace="acme", ordering="-last_updated")
api.create_repository(namespace="acme", name="release-images", is_private=True)
tags = api.get_repository_tags(namespace="acme", repository="release-images")
print(api.rate_limit)  # latest X-RateLimit-* snapshot

Every client method returns a uniform envelope: {"status_code": int, "data": ..., "rate_limit": {"limit", "remaining", "reset"}}.

MCP

Available MCP Tools

Auto-generated — do not edit (synced by the mcp-readme-table pre-commit hook).

Condensed action-routed tools (default — MCP_TOOL_MODE=condensed)

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

9 action-routed tool(s) (default) · 54 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (condensed default · verbose 1:1 · both). Auto-generated — do not edit.

MCP Configuration Examples

Install the connector-focused [mcp] extra. Examples use dockerhub-api[mcp] to add FastMCP / FastAPI through agent-connector-sdk; the required Agent Connector SDK core still carries epistemic-graph[full]. The [agent-runtime] extra additionally enables model orchestration.

stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "dockerhub-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "dockerhub-api[mcp]",
        "dockerhub-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "ADMINTOOL": "True",
        "AUDITTOOL": "True",
        "AUTHTOOL": "True",
        "DOCKERHUB_ALLOW_DESTRUCTIVE": "False",
        "DOCKERHUB_TLS_PROFILE": "system",
        "DOCKERHUB_TOKEN": "dckr_pat_your_personal_access_token",
        "DOCKERHUB_URL": "https://hub.docker.com",
        "DOCKERHUB_USERNAME": "your_dockerhub_username",
        "DOCKER_REGISTRY_AUTH_URL": "https://auth.docker.io/token",
        "DOCKER_REGISTRY_URL": "https://registry-1.docker.io",
        "DOCKER_SCOUT_URL": "https://api.scout.docker.com",
        "KGTOOL": "True",
        "ORGTOOL": "True",
        "REGISTRYTOOL": "True",
        "REPOSTOOL": "True",
        "SCIMTOOL": "True",
        "SCOUTTOOL": "True",
        "TEAMSTOOL": "True"
      }
    }
  }
}

Runtime references require an alias-aware launcher such as Arbora. Other launchers must omit those entries and inject the resolved values through their own runtime secret boundary.

Streamable-HTTP Transport (networked / production)

{
  "mcpServers": {
    "dockerhub-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "dockerhub-api[mcp]",
        "dockerhub-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "ADMINTOOL": "True",
        "AUDITTOOL": "True",
        "AUTHTOOL": "True",
        "DOCKERHUB_ALLOW_DESTRUCTIVE": "False",
        "DOCKERHUB_TLS_PROFILE": "system",
        "DOCKERHUB_TOKEN": "dckr_pat_your_personal_access_token",
        "DOCKERHUB_URL": "https://hub.docker.com",
        "DOCKERHUB_USERNAME": "your_dockerhub_username",
        "DOCKER_REGISTRY_AUTH_URL": "https://auth.docker.io/token",
        "DOCKER_REGISTRY_URL": "https://registry-1.docker.io",
        "DOCKER_SCOUT_URL": "https://api.scout.docker.com",
        "KGTOOL": "True",
        "ORGTOOL": "True",
        "REGISTRYTOOL": "True",
        "REPOSTOOL": "True",
        "SCIMTOOL": "True",
        "SCOUTTOOL": "True",
        "TEAMSTOOL": "True"
      }
    }
  }
}

Alternatively, connect to a pre-deployed Streamable-HTTP instance by url:

{
  "mcpServers": {
    "dockerhub-mcp": {
      "url": "http://localhost:8000/dockerhub-mcp/mcp"
    }
  }
}

Run a reviewed container image as a least-privilege stdio child (no listener or published port):

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e ADMINTOOL=True \
  -e AUDITTOOL=True \
  -e AUTHTOOL=True \
  -e DOCKERHUB_ALLOW_DESTRUCTIVE=False \
  -e DOCKERHUB_TLS_PROFILE=system \
  -e DOCKERHUB_TOKEN=dckr_pat_your_personal_access_token \
  -e DOCKERHUB_URL=https://hub.docker.com \
  -e DOCKERHUB_USERNAME=your_dockerhub_username \
  -e DOCKER_REGISTRY_AUTH_URL=https://auth.docker.io/token \
  -e DOCKER_REGISTRY_URL=https://registry-1.docker.io \
  -e DOCKER_SCOUT_URL=https://api.scout.docker.com \
  -e KGTOOL=True \
  -e ORGTOOL=True \
  -e REGISTRYTOOL=True \
  -e REPOSTOOL=True \
  -e SCIMTOOL=True \
  -e SCOUTTOOL=True \
  -e TEAMSTOOL=True \
  registry.example.invalid/dockerhub-api@sha256:<digest> dockerhub-mcp

For containerized network HTTP, supply an authenticated TLS ingress (or direct server TLS), exact MCP_ALLOWED_HOSTS, and an exact trusted-proxy CIDR policy through the operator-owned deployment profile. The generator does not emit an unauthenticated non-loopback listener.

Auto-generated from the code-read env surface (MCP_TOOL_MODE + package vars) — do not edit.

Additional Deployment Options

dockerhub-api can run as a local stdio process or container, or behind a remote network boundary. The Deployment guide carries the detailed transport contract.

• Local container — launch a reviewed immutable image as a least-privilege stdio child with no listener or published port.
• Remote URL — connect through an operator-supplied authenticated HTTPS ingress. Keep its URL, outbound identity references, trust profile, and exact MCP_ALLOWED_HOSTS in AgentConfig.

Safety Model

Concepts

The concept registry (CONCEPT:DH-OS.governance.hub-x) is documented in docs/concepts.md.

License

MIT — see LICENSE.

Governed capability contract

This package ships a compact canonical skill surface with specialist procedures kept as referenced workflows. The current MCP tools, skill metadata, connector_manifest.yml, ontology, mappings, shapes, fixtures, migrations, tool-schema fingerprints, and certification metadata form one versioned capability contract. Validate them together; do not rely on stale tool names or historical per-task skill wrappers.

Runtime endpoints, credentials, certificate trust, tenant identity, retention, and observability policy are deployment inputs and are never packaged values. See Configuration, trust, and privacy before enabling a network transport, connector ingestion, Arbora delegation, or trace export.

Environment Variables

Package environment variables

Inherited agent-connector-sdk variables (apply to every connector)

36 package + 16 inherited variable(s). Auto-generated from .env.example + the shared agent-connector-sdk set — do not edit.