docker/hub-mcp

The Docker Hub MCP Server is a Model Context Protocol (MCP) server that interfaces with Docker Hub APIs to make them accessible to LLMs, enabling intelligent content discovery and repository management.
Developers building with containers, especially in AI and LLM-powered workflows, often face inadequate context across the vast landscape of Docker Hub images. As a result, LLMs struggle to recommend the right images, and developers lose time manually searching instead of building.
Use Cases
- AI-powered image recommendations - LLMs access real-time Docker Hub data for accurate container image suggestions.
- Enhanced content discovery - AI tools help developers find the right images faster.
- Simplified Hub workflows - Manage Docker repositories and images using natural language.
Prerequisites
- Docker installed
- Node.js (version 22+)
- [Optional] A Docker Personal Access Token (PAT) with appropriate permissions
Setup
1. **Build**
2. **Run**
- Default args:
- transport: Choose between http or stdio (default: stdio)
- port=3000
- host=127.0.0.1 (HTTP transport only)
This starts the server with default settings and can only access public Docker Hub content.
> [!IMPORTANT]
> The http transport binds to 127.0.0.1 (loopback) by default and **requires
> authentication**. See Securing the HTTP transport
> before exposing it to a network.
Run in inspector [Optional]
The MCP Inspector provides a web interface to test your server:
Securing the HTTP transport
The stdio transport is only reachable by the local process that spawns it. The
http transport, however, dispatches every tool call using the server operator's
Docker Hub Personal Access Token (HUB_PAT_TOKEN). Anyone who can reach the HTTP
endpoint can therefore act as that Docker Hub identity — including creating and
modifying repositories. To prevent this, the HTTP transport is locked down by
default:
- **Loopback binding.** The listener binds to 127.0.0.1 unless you pass
--host= (for example --host=0.0.0.0 to expose it from a container).
- **Authentication required (fail-closed).** In http mode the server refuses to
start unless you either provide a bearer token or explicitly opt out. Set the
token via the MCP_AUTH_TOKEN environment variable; clients must then send it as
Authorization: Bearer on every request.
- **DNS-rebinding / CSRF protection.** Requests are rejected when the Host header
is not in the allow-list (loopback plus --host, extendable with
--allowed-hosts), or when they carry a browser Origin header that is not
listed in --allowed-origins. Non-browser MCP clients are unaffected.
Run the HTTP transport with authentication:
Expose it beyond loopback (e.g. inside a container), still authenticated:
| Flag / env var | Purpose |
| ------------------------- | --------------------------------------------------------------- |
| MCP_AUTH_TOKEN | Bearer token required on every /mcp request. |
| --host= | Address to bind (default 127.0.0.1). |
| --allowed-hosts=a,b | Extra Host header values to accept (comma-separated). |
| --allowed-origins=a,b | Browser Origin values to accept (comma-separated). |
| --allow-unauthenticated | Serve /mcp with **no** authentication. Insecure; opt-in only. |
> [!WARNING]
> --allow-unauthenticated disables authentication entirely and exposes your
> Docker Hub PAT to any client that can reach the port. Only use it on a trusted,
> isolated network.
Authenticate with docker
By default this MCP server can only query public content on Docker Hub. In order to manage your repositories you need to provide authentication.
Run with authentication
Run in inspector [Optional]
Usage in Docker Ask Gordon
You can configure Gordon to be a host that can interact with the Docker Hub MCP server.