Docker Hub MCP Server (hub-mcp) is a Model Context Protocol (MCP) server used to connect to the Docker Hub API, enabling large language models (LLMs) to access these APIs, thereby achieving intelligent content discovery and repository management. It is mainly aimed at developers using containers for development, especially in AI- and LLM-driven workflows. It solves the problem of insufficient context caused by the huge number of Docker Hub images, helps LLMs recommend the correct images, and reduces the time developers spend on manual searching.

Main capabilities

AI-driven image recommendations: LLMs can access real-time Docker Hub data to provide accurate container image suggestions.
Enhanced content discovery: AI tools help developers find suitable images faster.
Simplified Docker Hub workflows: Supports managing Docker repositories and images using natural language.

Environment requirements and how to run

Docker and Node.js (version 22 and above) need to be installed. Optionally, provide a Docker Personal Access Token (PAT) with the corresponding permissions. The build and run commands are as follows:

# 安装依赖
npm install

# 构建
npm run build

# 运行
npm start -- [--transport = http | stdio] [--port = 3000] [--host = 127.0.0.1]

Default parameters:transport Optional http or stdio (default stdio);port=3000；host=127.0.0.1(used only for HTTP transport). Under the default settings, the started server can only access public Docker Hub content.

HTTP transport binds to 127.0.0.1 (loopback address) by default and requires authentication. Before exposing it to the network, you need to read the "Securing HTTP Transport" section first.

You can also use the web interface provided by MCP Inspector to test the server (optional).

Securing HTTP Transport

Loopback binding: Unless --host=<addr>is passed in (for example, --host=0.0.0.0 to expose it from a container), the listener binds to 127.0.0.1 by default.
Mandatory authentication (fail closed): In http mode, unless a bearer token is provided or an explicit opt-out is chosen, the server refuses to start. The token can be set via the MCP_AUTH_TOKEN environment variable, and the client must send Authorization: Bearer <token>in every request.
DNS rebinding / CSRF protection: When the Host header is not in the allowlist (loopback addresses plus --host, extensible via --allowed-hosts ), or when the request carries a browser Origin header that is not listed in --allowed-origins , the request is rejected. Non-browser MCP clients are not affected.

An example of running HTTP transport with authentication is as follows:

# 根据文档，需设置 MCP_AUTH_TOKEN 并指定 transport http

If you need to expose it beyond the loopback address (for example, inside a container), authentication is still required.--allow-unauthenticated completely disables authentication and exposes your Docker Hub PAT to any client that can access the port. Use it only in trusted isolated networks.

Authentication

By default, this MCP server can only query public content on Docker Hub. To manage your own repositories, you need to provide authentication. At runtime, you can set the Docker Hub username and PAT token.

Using in Docker Ask Gordon

Gordon can be configured as a host that interacts with the Docker Hub MCP server. Ask Gordon is the personal AI assistant embedded in Docker Desktop and Docker CLI. Configuration steps include: create gordon-mcp.yml file in the working directory, replace the environment variables in it with the Docker Hub username and PAT token, then run docker build -t hub ..

Using in other MCP clients

Using with Claude Desktop

The build steps need to be completed first, then add the Docker Hub MCP Server configuration to claude_desktop_config.json . When configuring, note: if you use nvm to manage Node versions, you should fill in the node binary path in the command property (you can use which node search) to ensure the MCP server uses the correct Node version. The following values need to be replaced in the configuration:YOUR_DOCKER_HUB_USERNAME、YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN、/FULL/PATH/TO/YOUR/docker-hub-mcp-server. After saving the configuration, Claude Desktop must be fully restarted for the changes to take effect.

Using with VS Code

Add the Docker Hub MCP Server configuration to the VS Code user settings (JSON) (you can enter it in the Command Palette by typing Preferences: Open User Settings (JSON) to open it). Then open the Command Palette, type MCP: List Servers, select docker-hub, then select Start Server.

Main Tools and Capabilities

Repository Management and Image Push/Pull

As well as Docker Hardened Images related features.

search

Use the Search V4 API to search repositories and content. Supported parameters:

query: Search query parameter (string, required)
architectures: Filter by architecture (string, optional)
badges: Filter by image content type badge (string, optional)
categories: Filter by category (string, optional)
extension_reviewed: Filter by verified publisher (boolean, optional)
from: Number of documents to skip for pagination (number, optional)
images: Filter by image name (string, optional)
operating_systems: Filter by operating system (string, optional)
order: Change the result sorting (string, optional)
size: Maximum number of results to return (number, optional)
sort: Sort results by a search field (string, optional)
type: Filter by repository content type (string, optional)

Namespace Management

get_namespaces: Get the list of namespaces the user belongs to. Parameters:page(string, optional),page_size(string, optional).
list_repositories_by_namespace: List all repositories under the specified namespace. Parameters:namespace(string, required),content_types(string, optional),media_types(string, optional),name(string, optional),ordering(string, optional),page(number, optional),page_size(number, optional).
get_repository_info: Get repository information. Parameters:namespace(string, required),repository(string, required).
check_repository: Check whether a repository exists. Parameters:namespace(string, required),repository(string, required).
check_repository_tag: Check whether a specific tag exists in a repository. Parameters:namespace(string, required),repository(string, required),tag(string, required).
create_repository: Create a new repository in the specified namespace. Parameters:namespace(string, required),body(object, optional).
update_repository_info: Update repository information. Parameters:namespace(string, required),repository(string, required),body(object, optional).
list_repository_tags: List all tags in the repository. Parameters:namespace(string, required),repository(string, required),architecture(string, optional),os(string, optional),page(number, optional),page_size(number, optional).
read_repository_tag: Get the details of a specific repository tag. Parameters:namespace(string, required),repository(string, required),tag(string, required).

Docker Hardened Images

docker_hardened_images: Query Docker Hardened Images (DHI) for images in a namespace. Parameters:namespace(string, optional).

Use Cases

Developers need to quickly find suitable container images in AI/LLM workflows.
Manage Docker Hub repositories, tags, and namespaces using natural language.
Integrate Docker Hub operations into MCP clients such as Claude Desktop, VS Code, or Docker Ask Gordon.

Limitations and Notes

By default, only public Docker Hub content can be accessed; managing private repositories requires configuring authentication.
The HTTP transport binds to the loopback address by default and requires authentication. When exposing it to the network, pay attention to security configuration to prevent PAT leakage.
Requires Node.js 22+ and a Docker environment.
The project is licensed under the Apache License 2.0.
Information such as fees, pricing, and platform is not yet provided.

hub-mcp

About this tool