Skip to content
Back to search

hub-mcp

Docker Hub MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/docker--hub-mcp/badge.svg)](/listings/docker--hub-mcp)

HTML

<a href="/listings/docker--hub-mcp"><img src="/api/listings/docker--hub-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Build**

```bash npm install npm run build ```

2. **Run**

```bash npm start -- [--transport=http|stdio] [--port=3000] [--host=127.0.0.1] ```

- 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](#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:

npx @modelcontextprotocol/inspector node dist/index.js [--transport=http|stdio] [--port=3000]

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 414 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  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. The 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.
  4. 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.
  5. <p align="center">
  6. <img src="hubmcp.gif"
  7. alt="Demo"
  8. width="50%"
  9. style="border: 1px solid #ccc; border-radius: 8px;" />
  10. </p>
  11. ### Use Cases
  12. - AI-powered image recommendations - LLMs access real-time Docker Hub data for accurate container image suggestions.
  13. - Enhanced content discovery - AI tools help developers find the right images faster.
  14. - Simplified Hub workflows - Manage Docker repositories and images using natural language.
  15. ## Prerequisites
  16. - [Docker](https://docs.docker.com/get-docker/) installed
  17. - [Node.js](https://nodejs.org/) (version 22+)
  18. - [Optional] A [Docker Personal Access Token (PAT)](https://docs.docker.com/security/for-developers/access-tokens/) with appropriate permissions
  19. ## Setup
  20. 1. **Build**
  21. ```bash
  22. npm install
  23. npm run build
  24. ```
  25. 2. **Run**
  26. ```bash
  27. npm start -- [--transport=http|stdio] [--port=3000] [--host=127.0.0.1]
  28. ```
  29. - Default args:
  30. - `transport`: Choose between `http` or `stdio` (default: `stdio`)
  31. - `port=3000`
  32. - `host=127.0.0.1` (HTTP transport only)
  33. This starts the server with default settings and can only access public Docker Hub content.
  34. > [!IMPORTANT]
  35. > The `http` transport binds to `127.0.0.1` (loopback) by default and **requires
  36. > authentication**. See [Securing the HTTP transport](#securing-the-http-transport)
  37. > before exposing it to a network.
  38. ### Run in inspector [Optional]
  39. The MCP Inspector provides a web interface to test your server:
  40. ```
  41. npx @modelcontextprotocol/inspector node dist/index.js [--transport=http|stdio] [--port=3000]
  42. ```
  43. ## Securing the HTTP transport
  44. The `stdio` transport is only reachable by the local process that spawns it. The
  45. `http` transport, however, dispatches every tool call using the server operator's
  46. Docker Hub Personal Access Token (`HUB_PAT_TOKEN`). Anyone who can reach the HTTP
  47. endpoint can therefore act as that Docker Hub identity — including creating and
  48. modifying repositories. To prevent this, the HTTP transport is locked down by
  49. default:
  50. - **Loopback binding.** The listener binds to `127.0.0.1` unless you pass
  51. `--host=<addr>` (for example `--host=0.0.0.0` to expose it from a container).
  52. - **Authentication required (fail-closed).** In `http` mode the server refuses to
  53. start unless you either provide a bearer token or explicitly opt out. Set the
  54. token via the `MCP_AUTH_TOKEN` environment variable; clients must then send it as
  55. `Authorization: Bearer <token>` on every request.
  56. - **DNS-rebinding / CSRF protection.** Requests are rejected when the `Host` header
  57. is not in the allow-list (loopback plus `--host`, extendable with
  58. `--allowed-hosts`), or when they carry a browser `Origin` header that is not
  59. listed in `--allowed-origins`. Non-browser MCP clients are unaffected.
  60. Run the HTTP transport with authentication:
  61. ```bash
  62. MCP_AUTH_TOKEN=<a_long_random_secret> npm start -- --transport=http
  63. ```
  64. Expose it beyond loopback (e.g. inside a container), still authenticated:
  65. ```bash
  66. MCP_AUTH_TOKEN=<a_long_random_secret> npm start -- \
  67. --transport=http --host=0.0.0.0 \
  68. --allowed-hosts=my-host.internal --allowed-origins=https://my-app.example.com
  69. ```
  70. | Flag / env var | Purpose |
  71. | ------------------------- | --------------------------------------------------------------- |
  72. | `MCP_AUTH_TOKEN` | Bearer token required on every `/mcp` request. |
  73. | `--host=<addr>` | Address to bind (default `127.0.0.1`). |
  74. | `--allowed-hosts=a,b` | Extra `Host` header values to accept (comma-separated). |
  75. | `--allowed-origins=a,b` | Browser `Origin` values to accept (comma-separated). |
  76. | `--allow-unauthenticated` | Serve `/mcp` with **no** authentication. Insecure; opt-in only. |
  77. > [!WARNING]
  78. > `--allow-unauthenticated` disables authentication entirely and exposes your
  79. > Docker Hub PAT to any client that can reach the port. Only use it on a trusted,
  80. > isolated network.
  81. ## Authenticate with docker
  82. By default this MCP server can only query public content on Docker Hub. In order to manage your repositories you need to provide authentication.
  83. ### Run with authentication
  84. ```
  85. HUB_PAT_TOKEN=<a_pat_token> npm start -- [--username=<the_hub_username_for_the_pat>]
  86. ```
  87. ### Run in inspector [Optional]
  88. ```
  89. HUB_PAT_TOKEN=<a_pat_token> npx @modelcontextprotocol/inspector node dist/index.js[--username=<the_hub_username_for_the_pat>]
  90. ```
  91. ## Usage in Docker Ask Gordon
  92. You can configure Gordon to be a host that can interact with the Docker Hub MCP server.
  93. ### Gordon Setup
  94. [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.
  95. You can configure Gordon to be a client that can interact with the Docker Hub MCP server.
  96. 1. Create the [`gordon-mcp.yml` file](https://docs.docker.com/ai/gordon/mcp/yaml/) file in your working directory.
  97. 2. Replace environment variables in the `gordon-mcp.yml` with your Docker Hub username and a PAT token.
  98. ```
  99. services:
  100. hub:
  101. image: hub
  102. environment:
  103. - HUB_PAT_TOKEN=<your_pat_token>
  104. command:
  105. - --username=<your_hub_username>
  106. ```
  107. 2. Run `docker build -t hub .`
  108. 3. Run `docker ai`
  109. ## Usage in other MCP Clients
  110. ### Usage with Claude Desktop
  111. > NOTE: Make sure you have already built the application as mentioned in Step 1.
  112. 1. Add the Docker Hub MCP Server configuration to your `claude_desktop_config.json`:
  113. > 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
  114. #### For public repositories only:
  115. - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this repository
  116. ```json
  117. {
  118. "mcpServers": {
  119. "docker-hub": {
  120. "command": "node", // or absoulute binary path
  121. "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"]
  122. }
  123. }
  124. }
  125. ```
  126. #### For authenticated access (recommended):
  127. Replace the following values:
  128. - `YOUR_DOCKER_HUB_USERNAME` - Your Docker Hub username
  129. - `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` - Your Docker Hub Personal Access Token
  130. - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this
  131. ```json
  132. {
  133. "mcpServers": {
  134. "docker-hub": {
  135. "command": "node",
  136. "args": [
  137. "/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js",
  138. "--transport=stdio",
  139. "--username=YOUR_DOCKER_HUB_USERNAME"
  140. ],
  141. "env": {
  142. "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN"
  143. }
  144. }
  145. }
  146. }
  147. ```
  148. 2. Save the configuration file and completely restart Claude Desktop for the changes to take effect.
  149. ## Usage with VS Code
  150. 1. 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. #### For public repositories only:
  152. - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this repository
  153. ```json
  154. {
  155. "mcpServers": {
  156. "docker-hub": {
  157. "command": "node",
  158. "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"]
  159. }
  160. }
  161. }
  162. ```
  163. #### For authenticated access (recommended):
  164. Replace the following values:
  165. - `YOUR_DOCKER_HUB_USERNAME` - Your Docker Hub username
  166. - `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` - Your Docker Hub Personal Access Token
  167. - `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` - The complete path to where you cloned this
  168. ```json
  169. {
  170. "mcpServers": {
  171. "docker-hub": {
  172. "command": "node",
  173. "args": [
  174. "/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js",
  175. "--transport=stdio",
  176. "--username=YOUR_DOCKER_HUB_USERNAME"
  177. ],
  178. "env": {
  179. "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN"
  180. }
  181. }
  182. }
  183. }
  184. ```
  185. 2. Open the `Command Palette` and type `MCP: List Servers`.
  186. 3. Select `docker-hub` and select `Start Server`.
  187. ## Task Examples
  188. ### Finding images
  189. ```console
  190. # Search for official images
  191. $ docker ai "Search for official nginx images on Docker Hub"
  192. # Search for lightweight images to reduce deployment size and improve performance
  193. $ docker ai "Search for minimal Node.js images with small footprint"
  194. # Get the most recent tag of a base image
  195. $ docker ai "Show me the latest tag details for go"
  196. # Find a production-ready database with enterprise features and reliability
  197. $ docker ai "Search for production ready database images"
  198. # Compare Ubuntu versions to choose the right one for my project
  199. $ docker ai "Help me find the right Ubuntu version for my project"
  200. ```
  201. ### Repository Management
  202. ```console
  203. # Create a repository
  204. $ docker ai "Create a repository in my namespace"
  205. # List all repositories in my namespace
  206. $ docker ai "List all repositories in my namespace"
  207. # Find the largest repository in my namespace
  208. $ docker ai "Which of my repositories takes up the most space?"
  209. # Find repositories that haven't been updated recently
  210. $ docker ai "Which of my repositories haven't had any pushes in the last 60 days?"
  211. # Find which repositories are currently active and being used
  212. $ docker ai "Show me my most recently updated repositories"
  213. # Get details about a repository
  214. $ docker ai "Show me information about my '<repository-name>' repository"
  215. ```
  216. ### Pull/Push Images
  217. ```console
  218. # Pull latest PostgreSQL version
  219. $ docker ai "Pull the latest postgres image"
  220. # Push image to your Docker Hub repository
  221. $ docker ai "Push my <image-name> to my <repository-name> repository"
  222. ```
  223. ### Tag Management
  224. ```console
  225. # List all tags for a repository
  226. $ $ docker ai "Show me all tags for my '<repository-name>' repository"
  227. # Find the most recently pushed tag
  228. $ docker ai "What's the most recent tag pushed to my '<repository-name>' repository?"
  229. # List tags with architecture filtering
  230. $ docker ai "List tags for in the '<repository-name>' repository that support amd64 architecture"
  231. # Get detailed information about a specific tag
  232. $ docker ai "Show me details about the '<tag-name>' tag in the '<repository-name>' repository"
  233. # Check if a specific tag exists
  234. $ docker ai "Check if version 'v1.2.0' exists for my 'my-web-app' repository"
  235. ```
  236. ### Docker Hardened Images
  237. ```console
  238. # List available hardened images
  239. $ docker ai "What is the most secure image I can use to run a node.js application?"
  240. # Convert Dockerfile to use a hardened image
  241. $ docker ai "Can you help me update my Dockerfile to use a docker hardened image instead of the current one"
  242. ```
  243. ## Tools
  244. ### Search
  245. - **search** - Search repositories and content using Search V4 API
  246. - `query`: Search query parameter (string, required)
  247. - `architectures`: Filter on architectures (string, optional)
  248. - `badges`: Filter by image content type badges (string, optional)
  249. - `categories`: Filter on categories (string, optional)
  250. - `extension_reviewed`: Filter on reviewed extensions (boolean, optional)
  251. - `from`: Number of documents to skip for pagination (number, optional)
  252. - `images`: Filter on image names (string, optional)
  253. - `operating_systems`: Filter on operating systems (string, optional)
  254. - `order`: Change the ordering of results (string, optional)
  255. - `size`: Maximum number of results to return (number, optional)
  256. - `sort`: Sort results by search field (string, optional)
  257. - `type`: Filter on repository content type (string, optional)
  258. ### Namespace Management
  259. - **get_namespaces** - Get list of namespaces the user is a member of
  260. - `page`: Page number for pagination (string, optional)
  261. - `page_size`: Number of items per page (string, optional)
  262. ### Repository Management
  263. - **list_repositories_by_namespace** - List all repositories under the provided namespace
  264. - `namespace`: Repository namespace (string, required)
  265. - `content_types`: Comma-delimited list of content types (string, optional)
  266. - `media_types`: Comma-delimited list of media types (string, optional)
  267. - `name`: Search by repository name (string, optional)
  268. - `ordering`: Sort order (string, optional)
  269. - `page`: Page number (number, optional)
  270. - `page_size`: Number of items per page (number, optional)
  271. - **get_repository_info** - Get information about a repository
  272. - `namespace`: Repository namespace (string, required)
  273. - `repository`: Repository name (string, required)
  274. - **check_repository** - Check if a repository exists
  275. - `namespace`: Repository namespace (string, required)
  276. - `repository`: Repository name (string, required)
  277. - **check_repository_tag** - Check if a specific tag exists in a repository
  278. - `namespace`: Repository namespace (string, required)
  279. - `repository`: Repository name (string, required)
  280. - `tag`: Tag name (string, required)
  281. - **create_repository** - Create a new repository in the provided namespace
  282. - `namespace`: Repository namespace (string, required)
  283. - `body`: Request body data (object, optional)
  284. - **update_repository_info** - Update repository information
  285. - `namespace`: Repository namespace (string, required)
  286. - `repository`: Repository name (string, required)
  287. - `body`: Request body data (object, optional)
  288. ### Tag Management
  289. - **list_repository_tags** - List all tags for a repository
  290. - `namespace`: Repository namespace (string, required)
  291. - `repository`: Repository name (string, required)
  292. - `architecture`: Filter by architecture (string, optional)
  293. - `os`: Filter by operating system (string, optional)
  294. - `page`: Page number (number, optional)
  295. - `page_size`: Number of items per page (number, optional)
  296. - **read_repository_tag** - Get details of a specific repository tag
  297. - `namespace`: Repository namespace (string, required)
  298. - `repository`: Repository name (string, required)
  299. - `tag`: Tag name (string, required)
  300. ### Hardened Images
  301. - **docker_hardened_images** - Query for mirrored Docker Hardened Images (DHI) in the namespace
  302. - `namespace`: The namespace to query for mirrored hardened repositories (string, optional)
  303. ## Licensing
  304. [docker/hub-mcp](https://github.com/docker/hub-mcp) is licensed under the Apache License, Version 2.0. See
  305. [LICENSE](https://github.com/docker/docker/blob/master/LICENSE) for the full
  306. license text.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.