How to Access Docker Hub Repositories with an MCP Server

The official docker/hub-mcp server acts as a bridge between MCP-compatible clients and Docker Hub's REST API, exposing standardized tools like docker_hub/list_repos and docker_hub/search that let AI agents query repositories, tags, and hardened images without writing custom integration code.

The punkpeye/awesome-mcp-servers repository curates docker/hub-mcp as the official Model Context Protocol (MCP) server for Docker Hub. When you need to access Docker Hub repositories with an MCP server, this implementation wraps the Docker Hub API into JSON-RPC tool calls, handling authentication, request forwarding, and structured responses automatically.

Architecture and Components

The server architecture follows a straightforward proxy pattern. The docker/hub-mcp container receives MCP requests via HTTP (or stdio), attaches your Docker Hub access token to outgoing calls, and returns normalized JSON to the client.

• Docker Hub API: Provides underlying data about repositories, tags, and Docker Hardened Images.
• docker/hub-mcp server: Wraps the API in MCP format, listening on port 5000 by default at the /mcp endpoint.
• MCP client: Any compatible client (Claude Desktop, Cursor, or custom scripts) sends JSON-RPC requests such as docker_hub/list_repos.
• Authentication: Requires a DOCKER_HUB_TOKEN environment variable, which the server injects into API requests as a Bearer token.

This architecture is officially documented in the awesome-mcp-servers list, specifically at line 1241 of the README, which notes the server provides "access to repositories, hub search and Docker Hardened Images."

Installation and Configuration

Pull the Official Image

The server is distributed as a Docker image on Docker Hub. Pull the latest version:

docker pull docker/hub-mcp:latest

Generate a Docker Hub Access Token

The server requires authentication to query private repositories or higher-rate public endpoints. Create a personal access token:

1. Log in to Docker Hub → Account Settings → Security → New Access Token.
2. Provide a descriptive name (e.g., "mcp-server").
3. Copy the generated token.

Start the Server Container

Run the container, passing your token as an environment variable and exposing port 5000:

docker run -d \
  -p 5000:5000 \
  -e DOCKER_HUB_TOKEN=<your-token> \
  --name hub-mcp \
  docker/hub-mcp:latest

Verify the server health:

curl http://localhost:5000/health

You should receive {"status":"ok"} before proceeding.

Querying Docker Hub via MCP Tools

With the server running at http://localhost:5000/mcp, you can invoke tools using standard JSON-RPC POST requests.

List Repositories by Namespace

To retrieve all repositories owned by a specific user or organization, use the docker_hub/list_repos method:

curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "method": "docker_hub/list_repos",
        "params": { "namespace": "my-org" },
        "id": 1
      }' | jq .

The response returns an array of repository names:

{
  "id": 1,
  "result": [
    "my-org/app-frontend",
    "my-org/app-backend",
    "my-org/database"
  ]
}

Search the Docker Hub Catalog

The docker_hub/search tool queries the Docker Hub catalog with pagination support:

curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "method": "docker_hub/search",
        "params": { "query": "nginx", "page": 1, "page_size": 5 },
        "id": 2
      }' | jq .

Retrieve Image Metadata

To inspect specific tags, layers, or Docker Hardened Image details, call docker_hub/get_image:

curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "method": "docker_hub/get_image",
        "params": {
          "name": "library/redis",
          "tag": "latest"
        },
        "id": 3
      }' | jq .

Programmatic Integration with Python

You can integrate these tools into Python applications using standard HTTP requests:

import requests
import json

MCP_ENDPOINT = "http://localhost:5000/mcp"

def mcp_call(method, params):
    payload = {"method": method, "params": params, "id": 1}
    r = requests.post(MCP_ENDPOINT, json=payload)
    r.raise_for_status()
    return r.json()["result"]

# List repos for the "my-org" namespace

repos = mcp_call("docker_hub/list_repos", {"namespace": "my-org"})
print(repos)

This pattern allows AI agents to dynamically discover and interact with Docker Hub content without hard-coding API endpoints.

Implementation Details and Source Files

The docker/hub-mcp implementation is organized into three key components:

• cmd/server/main.go: Initializes the HTTP server, registers MCP handlers, and reads the DOCKER_HUB_TOKEN environment variable at startup.
• internal/dockerhub/client.go: Implements a thin HTTP client wrapper around the Docker Hub API, managing authentication headers and retry logic.
• tools/docker_hub.go: Defines the concrete MCP tool implementations, mapping JSON-RPC method names like docker_hub/list_repos to internal API calls.

These files demonstrate how the server translates MCP semantics into Docker Hub REST operations, handling error responses and rate limiting transparently.

Summary

• The docker/hub-mcp server is the official MCP integration for Docker Hub, listed in punkpeye/awesome-mcp-servers.
• It exposes three primary tools: docker_hub/list_repos, docker_hub/search, and docker_hub/get_image.
• Authentication requires a Docker Hub personal access token passed via the DOCKER_HUB_TOKEN environment variable.
• The server runs as a container on port 5000, exposing a /mcp endpoint for JSON-RPC requests.
• Source files cmd/server/main.go, internal/dockerhub/client.go, and tools/docker_hub.go implement the core logic.

Frequently Asked Questions

How do I authenticate the MCP server with Docker Hub?

You must generate a personal access token from Docker Hub's Account Settings → Security page, then supply it via the DOCKER_HUB_TOKEN environment variable when running the container. The server automatically attaches this token as a Bearer header to all outgoing API requests.

What MCP tools are available for Docker Hub access?

The server exposes docker_hub/list_repos for listing repositories by namespace, docker_hub/search for catalog queries with pagination, and docker_hub/get_image for retrieving detailed image metadata including tags and layers. These are implemented in the tools/docker_hub.go source file.

Can I run the server without Docker?

While the primary distribution method is the docker/hub-mcp container, you can compile the Go source code directly from the repository. The entry point in cmd/server/main.go initializes the HTTP listener, allowing you to run the binary standalone if you prefer not to use containerization.

Where is the official MCP server listed?

The docker/hub-mcp server is officially catalogued in the punkpeye/awesome-mcp-servers repository, specifically referenced at line 1241 of the README as the official MCP server for Docker Hub interactions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}