# How to Access Docker Hub Repositories with an MCP Server

> Learn to access Docker Hub repositories with an MCP server. Utilize standardized tools for AI agents to query repositories and tags efficiently without custom code.

- Repository: [Frank Fiegel/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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:

```bash
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`:

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

```

Verify the server health:

```bash
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:

```bash
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:

```json
{
  "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:

```bash
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`:

```bash
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:

```python
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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/cmd/server/main.go), [`internal/dockerhub/client.go`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/internal/dockerhub/client.go), and [`tools/docker_hub.go`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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.