Docker Hub MCP Server

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

   Terminal

   Copy

   npm install
   npm run build
   

2. Run

   Terminal

   Copy

    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 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]

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=<addr> (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 <token> 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:

MCP_AUTH_TOKEN=<a_long_random_secret> npm start -- --transport=http

Expose it beyond loopback (e.g. inside a container), still authenticated:

MCP_AUTH_TOKEN=<a_long_random_secret> npm start -- \
  --transport=http --host=0.0.0.0 \
  --allowed-hosts=my-host.internal --allowed-origins=https://my-app.example.com

[!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

HUB_PAT_TOKEN=<a_pat_token> npm start -- [--username=<the_hub_username_for_the_pat>]

Run in inspector [Optional]

HUB_PAT_TOKEN=<a_pat_token> npx @modelcontextprotocol/inspector node dist/index.js[--username=<the_hub_username_for_the_pat>]

Usage in Docker Ask Gordon

You can configure Gordon to be a host that can interact with the Docker Hub MCP server.

Gordon Setup

Ask 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.

You can configure Gordon to be a client that can interact with the Docker Hub MCP server.

1. Create the gordon-mcp.yml file file in your working directory.
2. Replace environment variables in the gordon-mcp.yml with your Docker Hub username and a PAT token.

services:
  hub:
    image: hub
    environment:
      - HUB_PAT_TOKEN=<your_pat_token>
    command:
      - --username=<your_hub_username>

2. Run docker build -t hub .
3. Run docker ai

Usage in other MCP Clients

Usage with Claude Desktop

NOTE: Make sure you have already built the application as mentioned in Step 1.

1. Add the Docker Hub MCP Server configuration to your claude_desktop_config.json:

NOTE: if you are using 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

For public repositories only:

• /FULL/PATH/TO/YOUR/docker-hub-mcp-server - The complete path to where you cloned this repository

{
    "mcpServers": {
        "docker-hub": {
            "command": "node", // or absoulute binary path
            "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"]
        }
    }
}

For authenticated access (recommended):

Replace the following values:

• YOUR_DOCKER_HUB_USERNAME - Your Docker Hub username
• YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN - Your Docker Hub Personal Access Token
• /FULL/PATH/TO/YOUR/docker-hub-mcp-server - The complete path to where you cloned this

{
    "mcpServers": {
        "docker-hub": {
            "command": "node",
            "args": [
                "/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js",
                "--transport=stdio",
                "--username=YOUR_DOCKER_HUB_USERNAME"
            ],
            "env": {
                "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN"
            }
        }
    }
}

2. Save the configuration file and completely restart Claude Desktop for the changes to take effect.

Usage with VS Code

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).

For public repositories only:

• /FULL/PATH/TO/YOUR/docker-hub-mcp-server - The complete path to where you cloned this repository

{
    "mcpServers": {
        "docker-hub": {
            "command": "node",
            "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"]
        }
    }
}

For authenticated access (recommended):

Replace the following values:

• YOUR_DOCKER_HUB_USERNAME - Your Docker Hub username
• YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN - Your Docker Hub Personal Access Token
• /FULL/PATH/TO/YOUR/docker-hub-mcp-server - The complete path to where you cloned this

{
    "mcpServers": {
        "docker-hub": {
            "command": "node",
            "args": [
                "/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js",
                "--transport=stdio",
                "--username=YOUR_DOCKER_HUB_USERNAME"
            ],
            "env": {
                "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN"
            }
        }
    }
}

2. Open the Command Palette and type MCP: List Servers.
3. Select docker-hub and select Start Server.

Task Examples

Finding images

# Search for official images
$ docker ai "Search for official nginx images on Docker Hub"

# Search for lightweight images to reduce deployment size and improve performance
$ docker ai "Search for minimal Node.js images with small footprint"

# Get the most recent tag of a base image
$ docker ai "Show me the latest tag details for go"

# Find a production-ready database with enterprise features and reliability
$ docker ai "Search for production ready database images"

# Compare Ubuntu versions to choose the right one for my project
$ docker ai "Help me find the right Ubuntu version for my project"

Repository Management

# Create a repository
$ docker ai "Create a repository in my namespace"