Docker Hub MCP Server

1# Docker Hub MCP Server
2[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/docker/hub-mcp)](https://archestra.ai/mcp-catalog/docker__hub-mcp)
3 
4The Docker Hub MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that interfaces with Docker Hub APIs to make them accessible to LLMs, enabling intelligent content discovery and repository management.
5 
6Developers 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.
7 
8<p align="center">
9  <img src="hubmcp.gif" 
10       alt="Demo"
11       width="50%" 
12       style="border: 1px solid #ccc; border-radius: 8px;" />
13</p>
14 
15### Use Cases
16 
17- AI-powered image recommendations - LLMs access real-time Docker Hub data for accurate container image suggestions.
18- Enhanced content discovery - AI tools help developers find the right images faster.
19- Simplified Hub workflows - Manage Docker repositories and images using natural language.
20 
21## Prerequisites
22 
23- [Docker](https://docs.docker.com/get-docker/) installed
24- [Node.js](https://nodejs.org/) (version 22+)
25- [Optional] A [Docker Personal Access Token (PAT)](https://docs.docker.com/security/for-developers/access-tokens/) with appropriate permissions
26 
27## Setup
28 
291. **Build**
30 
31    ```bash
32    npm install
33    npm run build
34    ```
35 
362. **Run**
37 
38    ```bash
39     npm start -- [--transport=http|stdio] [--port=3000]
40    ```
41 
42- Default args:
43  - `transport`: Choose between `http` or `stdio` (default: `stdio`)
44  - `port=3000`
45    This starts the server with default settings and can only access public Docker Hub content.
46 
47### Run in inspector [Optional]
48 
49The MCP Inspector provides a web interface to test your server:
50 
51```
52npx @modelcontextprotocol/inspector node dist/index.js [--transport=http|stdio] [--port=3000]
53```
54 
55## Authenticate with docker
56 
57By default this MCP server can only query public content on Docker Hub. In order to manage your repositories you need to provide authentication.
58 
59### Run with authentication
60 
61```
62HUB_PAT_TOKEN=<a_pat_token> npm start -- [--username=<the_hub_username_for_the_pat>]
63```
64 
65### Run in inspector [Optional]
66 
67```
68HUB_PAT_TOKEN=<a_pat_token> npx @modelcontextprotocol/inspector node dist/index.js[--username=<the_hub_username_for_the_pat>]
69```
70## Usage in Docker Ask Gordon
71You can configure Gordon to be a host that can interact with the Docker Hub MCP server.
72 
73### Gordon Setup
74 
75[Ask Gordon](https://docs.docker.com/ai/gordon/) is your personal AI assistant embedded in Docker Desktop and the Docker CLI. It's designed to streamline your workflow and help you make the most of the Docker ecosystem.
76 
77You can configure Gordon to be a client that can interact with the Docker Hub MCP server.
78 
791. Create the [`gordon-mcp.yml` file](https://docs.docker.com/ai/gordon/mcp/yaml/) file in your working directory.
802. Replace environment variables in the `gordon-mcp.yml`  with your Docker Hub username and a PAT token.
81 
82```
83services:
84  hub:
85    image: hub
86    environment:
87      - HUB_PAT_TOKEN=<your_pat_token>
88    command:
89      - --username=<your_hub_username>
90```
91 
922. Run `docker build -t hub .`
933. Run `docker ai`
94 
95## Usage in other MCP Clients
96 
97### Usage with Claude Desktop
98 
99> NOTE: Make sure you have already built the application as mentioned in Step 1.
100 
1011. Add the Docker Hub MCP Server configuration to your `claude_desktop_config.json`:
102 
103> NOTE: if you are using [nvm](https://github.com/nvm-sh/nvm) to manage node versions, you should put the node binary path in the `command` property. This ensure MCP server runs with the right node version. You can find your binary path by running `which node` in your shell
104 
105#### For public repositories only:
106 
107- `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this repository
108 
109```json
110{
111    "mcpServers": {
112        "docker-hub": {
113            "command": "node", // or absoulute binary path
114            "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"]
115        }
116    }
117}
118```
119 
120#### For authenticated access (recommended):
121 
122Replace the following values:
123 
124- `YOUR_DOCKER_HUB_USERNAME` - Your Docker Hub username
125- `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` - Your Docker Hub Personal Access Token
126- `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this
127 
128```json
129{
130    "mcpServers": {
131        "docker-hub": {
132            "command": "node",
133            "args": [
134                "/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js",
135                "--transport=stdio",
136                "--username=YOUR_DOCKER_HUB_USERNAME"
137            ],
138            "env": {
139                "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN"
140            }
141        }
142    }
143}
144```
145 
1462. Save the configuration file and completely restart Claude Desktop for the changes to take effect.
147 
148## Usage with VS Code
149 
1501. Add the Docker Hub MCP Server configuration to your User Settings (JSON) file in VS Code. You can do this by opening the `Command Palette` and typing `Preferences: Open User Settings (JSON)`.
151 
152#### For public repositories only:
153 
154- `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this repository
155 
156```json
157{
158    "mcpServers": {
159        "docker-hub": {
160            "command": "node",
161            "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"]
162        }
163    }
164}
165```
166 
167#### For authenticated access (recommended):
168 
169Replace the following values:
170 
171- `YOUR_DOCKER_HUB_USERNAME` - Your Docker Hub username
172- `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` - Your Docker Hub Personal Access Token
173- `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this
174 
175```json
176{
177    "mcpServers": {
178        "docker-hub": {
179            "command": "node",
180            "args": [
181                "/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js",
182                "--transport=stdio",
183                "--username=YOUR_DOCKER_HUB_USERNAME"
184            ],
185            "env": {
186                "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN"
187            }
188        }
189    }
190}
191```
192 
1932. Open the `Command Palette` and type `MCP: List Servers`.
1943. Select `docker-hub` and select `Start Server`.
195 
196## Task Examples
197 
198### Finding images
199 
200```console
201# Search for official images
202$ docker ai "Search for official nginx images on Docker Hub"
203 
204# Search for lightweight images to reduce deployment size and improve performance
205$ docker ai "Search for minimal Node.js images with small footprint"
206 
207# Get the most recent tag of a base image
208$ docker ai "Show me the latest tag details for go"
209 
210# Find a production-ready database with enterprise features and reliability
211$ docker ai "Search for production ready database images"
212 
213# Compare Ubuntu versions to choose the right one for my project
214$ docker ai "Help me find the right Ubuntu version for my project"
215```
216 
217### Repository Management
218 
219```console
220# Create a repository
221$ docker ai "Create a repository in my namespace"
222 
223# List all repositories in my namespace
224$ docker ai "List all repositories in my namespace"
225 
226# Find the largest repository in my namespace
227$ docker ai "Which of my repositories takes up the most space?"
228 
229# Find repositories that haven't been updated recently
230$ docker ai "Which of my repositories haven't had any pushes in the last 60 days?"
231 
232# Find which repositories are currently active and being used
233$ docker ai "Show me my most recently updated repositories"
234 
235# Get details about a repository
236$ docker ai "Show me information about my '<repository-name>' repository"
237```
238 
239### Pull/Push Images
240 
241```console
242# Pull latest PostgreSQL version
243$ docker ai "Pull the latest postgres image"
244 
245# Push image to your Docker Hub repository
246$ docker ai "Push my <image-name> to my <repository-name> repository"
247```
248 
249### Tag Management
250 
251```console
252# List all tags for a repository
253$ $ docker ai "Show me all tags for my '<repository-name>' repository"
254 
255# Find the most recently pushed tag
256$ docker ai "What's the most recent tag pushed to my '<repository-name>' repository?"
257 
258# List tags with architecture filtering
259$ docker ai "List tags for in the '<repository-name>' repository that support amd64 architecture"
260 
261# Get detailed information about a specific tag
262$ docker ai "Show me details about the '<tag-name>' tag in the '<repository-name>' repository"
263 
264# Check if a specific tag exists
265$ docker ai "Check if version 'v1.2.0' exists for my 'my-web-app' repository"
266```
267 
268### Docker Hardened Images
269 
270```console
271# List available hardened images
272$ docker ai "What is the most secure image I can use to run a node.js application?"
273 
274# Convert Dockerfile to use a hardened image
275$ docker ai "Can you help me update my Dockerfile to use a docker hardened image instead of the current one"
276```
277 
278## Tools
279 
280### Search
281 
282- **search** - Search repositories and content using Search V4 API
283    - `query`: Search query parameter (string, required)
284    - `architectures`: Filter on architectures (string, optional)
285    - `badges`: Filter by image content type badges (string, optional)
286    - `categories`: Filter on categories (string, optional)
287    - `extension_reviewed`: Filter on reviewed extensions (boolean, optional)
288    - `from`: Number of documents to skip for pagination (number, optional)
289    - `images`: Filter on image names (string, optional)
290    - `operating_systems`: Filter on operating systems (string, optional)
291    - `order`: Change the ordering of results (string, optional)
292    - `size`: Maximum number of results to return (number, optional)
293    - `sort`: Sort results by search field (string, optional)
294    - `type`: Filter on repository content type (string, optional)
295 
296### Namespace Management
297 
298- **get_namespaces** - Get list of namespaces the user is a member of
299    - `page`: Page number for pagination (string, optional)
300    - `page_size`: Number of items per page (string, optional)
301 
302### Repository Management
303 
304- **list_repositories_by_namespace** - List all repositories under the provided namespace
305    - `namespace`: Repository namespace (string, required)
306    - `content_types`: Comma-delimited list of content types (string, optional)
307    - `media_types`: Comma-delimited list of media types (string, optional)
308    - `name`: Search by repository name (string, optional)
309    - `ordering`: Sort order (string, optional)
310    - `page`: Page number (number, optional)
311    - `page_size`: Number of items per page (number, optional)
312 
313- **get_repository_info** - Get information about a repository
314    - `namespace`: Repository namespace (string, required)
315    - `repository`: Repository name (string, required)
316 
317- **check_repository** - Check if a repository exists
318    - `namespace`: Repository namespace (string, required)
319    - `repository`: Repository name (string, required)
320 
321- **check_repository_tag** - Check if a specific tag exists in a repository
322    - `namespace`: Repository namespace (string, required)
323    - `repository`: Repository name (string, required)
324    - `tag`: Tag name (string, required)
325 
326- **create_repository** - Create a new repository in the provided namespace
327    - `namespace`: Repository namespace (string, required)
328    - `body`: Request body data (object, optional)
329 
330- **update_repository_info** - Update repository information
331    - `namespace`: Repository namespace (string, required)
332    - `repository`: Repository name (string, required)
333    - `body`: Request body data (object, optional)
334 
335### Tag Management
336 
337- **list_repository_tags** - List all tags for a repository
338    - `namespace`: Repository namespace (string, required)
339    - `repository`: Repository name (string, required)
340    - `architecture`: Filter by architecture (string, optional)
341    - `os`: Filter by operating system (string, optional)
342    - `page`: Page number (number, optional)
343    - `page_size`: Number of items per page (number, optional)
344- **read_repository_tag** - Get details of a specific repository tag
345    - `namespace`: Repository namespace (string, required)
346    - `repository`: Repository name (string, required)
347    - `tag`: Tag name (string, required)
348 
349### Hardened Images
350 
351- **docker_hardened_images** - Query for mirrored Docker Hardened Images (DHI) in the namespace
352    - `namespace`: The namespace to query for mirrored hardened repositories (string, optional)
353 
354## Licensing
355 
356[docker/hub-mcp](https://github.com/docker/hub-mcp) is licensed under the Apache License, Version 2.0. See
357[LICENSE](https://github.com/docker/docker/blob/master/LICENSE) for the full
358license text.
359