How to add Docker Hub MCP Server to Windsurf

Official Docker Hub MCP server for searching images, reading metadata and managing repositories. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 250★ · stdio · apikey · official

Windsurf config for Docker Hub MCP Server

git clone https://github.com/docker/hub-mcp && cd hub-mcp && npm install && npm run build && node dist/index.js --transport=stdio --username=<your-hub-username>

{
  "mcpServers": {
    "docker-hub-mcp-server": {
      "command": "node",
      "args": [
        "/absolute/path/to/hub-mcp/dist/index.js",
        "--transport=stdio",
        "--username=<your-docker-hub-username>"
      ],
      "env": {
        "HUB_PAT_TOKEN": "<your-docker-hub-pat>"
      }
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Docker Hub MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Docker Hub MCP Server's tools become available to Cascade.

Before you start

Node.js 22 or higher
Docker installed (for building/running the containerized server)
Optional but recommended: a Docker Hub Personal Access Token from your Docker Hub account settings, set via HUB_PAT_TOKEN (plus --username for your Hub username)
An MCP-compatible client (e.g. Claude Desktop, Cursor, VS Code)

What Docker Hub MCP Server can do in Windsurf

search

Search Docker Hub repositories and content.

get_repository_info

Fetch details about a specific repository.

check_repository

Verify whether a repository exists.

check_repository_tag

Confirm a specific tag is available on a repository.

list_repository_tags

List all tags for a repository.

read_repository_tag

Get metadata (digest, details) for a specific tag.

list_repositories_by_namespace

List repositories within a namespace/organization.

get_namespaces

Retrieve the namespaces the authenticated user belongs to.

Security

A Docker Hub PAT can push, pull and modify repositories in your namespace; scope it to read-only when you only need image discovery. Do not commit the token and rotate it if exposed.

Docker Hub MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Docker Hub MCP Server config there under the "mcpServers" key and restart the client.

Is Docker Hub MCP Server safe to use with Windsurf?

A Docker Hub PAT can push, pull and modify repositories in your namespace; scope it to read-only when you only need image discovery. Do not commit the token and rotate it if exposed.

Is authentication required?

No for public, read-only discovery. A Docker Hub Personal Access Token (HUB_PAT_TOKEN) is needed for private repos, repository management, and higher rate limits.

Where do I get the token?

Create a Personal Access Token in your Docker Hub account security settings, then set it as the HUB_PAT_TOKEN environment variable.

Is it published to npm?

It is distributed via the docker/hub-mcp GitHub repo; you clone it and run npm install / npm run build / npm start rather than installing a published npm package.

View repo Full Docker Hub MCP Server page