ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Run an MCP Server from Docker Hub

Run Docker’s Hub MCP server from a container, connect it to Claude or another MCP client, authenticate safely, and troubleshoot common failures.

By the ScreenshotNeo team1 October 20267 min read

To run a published MCP server from Docker Hub, configure your MCP client to start Docker with the server image as a stdio subprocess. Docker’s documented Docker Hub example uses dhi.io/hub-mcp:

{
  "mcpServers": {
    "docker-hub": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "dhi.io/hub-mcp"]
    }
  }
}

Before the first pull, authenticate to the Hardened Images registry:

docker login dhi.io

This route starts the container when the client starts the MCP server. --rm removes the stopped container, and -i keeps standard input open for the MCP stdio connection. The example server searches and manages Docker Hub image and repository information; replace the image and arguments when you use another MCP server.

What you need

  • Docker Engine or Docker Desktop with the docker command available to the MCP client.
  • An MCP-compatible client such as Claude Desktop, Claude Code, Codex, VS Code, Cursor, or another client that supports a local stdio server.
  • Permission to pull the image from its registry.
  • Credentials only if the server needs authenticated or private-repository access.

Check the installation before editing client configuration:

docker version
docker run --rm hello-world

Run Docker Hub MCP from an MCP client

1. Log in to the registry

The Hardened Images guide requires a registry login before pulling its example image:

docker login dhi.io

Use the credential flow supported by your organization. Do not put a reusable registry password or access token directly in a configuration file that is committed to source control.

2. Add the server entry

Paste the documented entry into your client’s MCP configuration. The exact file location and reload command depend on the client.

{
  "mcpServers": {
    "docker-hub": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "dhi.io/hub-mcp"]
    }
  }
}

3. Restart and verify

  1. Save the configuration.
  2. Restart or refresh the client using its documented procedure.
  3. Confirm that docker-hub appears connected or enabled.
  4. Send a low-risk request such as Search for official nginx images on Docker Hub.

If the client exposes a server-list command, use it after configuration. Docker’s Toolkit documentation gives claude mcp list for Claude Code and codex mcp list for Codex as verification examples.

Authenticated access to private repositories

Public Docker Hub discovery can work without a Hub personal access token. Private repositories and repository-management operations require authentication. The Hardened Images example passes a token as HUB_PAT_TOKEN and supplies the Docker Hub username:

{
  "mcpServers": {
    "docker-hub": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "HUB_PAT_TOKEN=your-access-token",
        "dhi.io/hub-mcp",
        "--username", "<your username>"
      ]
    }
  }
}

Prefer your client’s secret store or an environment-injection mechanism when available. If you must use an environment variable, keep the token outside version control and rotate it when it is no longer needed.

Docker MCP Toolkit: the managed alternative

Docker Desktop MCP Toolkit is a different workflow from calling docker run directly. It provides a catalog, profiles, and a gateway that connects containerized MCP servers to AI clients.

  1. Enable MCP Toolkit in Docker Desktop.
  2. Create or select a profile.
  3. Add the desired server from the catalog.
  4. Enter any required configuration fields.
  5. Connect your AI client and confirm the server is enabled.
  6. Send a prompt that invokes one of the server’s tools.

For a compatible client configured manually, Docker documents running the gateway over stdio:

docker mcp gateway run --profile my_profile

The current Toolkit interface instructions target Docker Desktop 4.62 and later. Earlier releases can have different menus and controls. Choose Toolkit when you want Docker to manage a catalog and profile; choose direct docker run when you already know the registry image and need a local stdio subprocess.

Build and run the server from source

The Docker hub-mcp repository documents a source installation for readers who need to inspect or modify the server. Its prerequisites include Docker and Node.js 22 or later.

git clone <the hub-mcp repository URL from Docker’s documentation>
cd hub-mcp
npm install
npm run build
npm start

The source project documents stdio as the default transport and HTTP as an alternative, with port 3000 as the HTTP default. Public Docker Hub queries can run without a PAT; authenticated repository management needs the documented PAT and username values. Use the repository’s current instructions for the exact clone URL and client configuration shape.

Choosing the right route

Route Best for Trade-off
Direct image invocation Starting a known image from a local MCP client You manage the image, arguments, secrets, and client JSON
MCP Toolkit Catalog discovery, profiles, and managed client connections Requires Docker Desktop Toolkit and its version-specific interface
Source build Inspecting or changing the server You maintain Node dependencies, builds, and runtime settings

Architecture and portability

The client launches Docker, Docker pulls or reuses the image, and the container communicates with the client over standard input and output. This is local process integration; it is not the same as connecting to a remote MCP endpoint.

Check the image manifest and host compatibility before relying on a server across machines. Docker’s image-building guidance recommends publishing multi-platform images for local clients, including amd64 and arm64. Confirm that the specific image you select actually provides the platforms your users need.

Security checklist

  • Use the smallest Hub token scope that supports the operations you need.
  • Keep HUB_PAT_TOKEN out of Git repositories, screenshots, logs, and shared client exports.
  • Review the image name and registry before the first pull; a similar name can point to a different publisher.
  • Pin an image digest in controlled deployments when your registry workflow supports it.
  • Do not mount the host Docker socket into an MCP container unless the server specifically requires it and you understand the resulting host access.
  • Limit private-repository access to the client and user that require it.

Troubleshooting

“docker: command not found”

Cause: Docker is not installed, or the MCP client cannot see the executable on its PATH.

Fix: Start Docker Desktop or the Docker daemon, verify docker version in the same environment that launches the client, and configure the client with an absolute Docker path if it does not inherit your shell PATH.

Registry authentication fails

Cause: The registry login was skipped, expired, or performed against the wrong registry.

Fix: Run docker login dhi.io, complete the supported credential flow, and retry the pull. Do not confuse a Docker Hub account login with the dhi.io registry login required by the documented Hardened Images example.

Image pull denied

Cause: The image name is wrong, the registry is unavailable, or your account cannot access it.

Fix: Check the exact image reference, test a direct pull, and confirm registry permissions:

docker pull dhi.io/hub-mcp

The client shows the server as disconnected

Cause: Invalid JSON, an unsupported configuration key, Docker not running, or a process that exits immediately.

Fix: Validate the client’s configuration format, run the Docker command manually, inspect the client’s MCP logs, and confirm that -i is present for stdio.

Private repositories return no data

Cause: The PAT was not passed to the container, the username argument is missing, or the token lacks permission.

Fix: Add -e HUB_PAT_TOKEN=... and --username as shown in the documented example, then create a token with the required repository scope.

Toolkit menus do not match the guide

Cause: Docker Desktop is older than the version covered by the current instructions.

Fix: Check your Docker Desktop version and follow the documentation for that release. The current Toolkit guide targets 4.62 and later.

The server works on one computer but not another

Cause: Architecture differences, missing image platform support, different Docker versions, or client-specific configuration.

Fix: Compare docker version, host architecture, image manifest platforms, registry credentials, and the client configuration on both machines.

Performance and reliability notes

  • The first request can be slower because Docker must pull the image. Later starts can reuse the local image until it is removed or updated.
  • --rm keeps stopped containers from accumulating, but it also removes the container’s writable layer when the process exits. Persist data only through an explicitly configured volume or external service.
  • For repeated use, keep Docker running and avoid unnecessary image cleanup between client sessions.
  • For team deployments, document the image reference, required architecture, token scope, client configuration, and upgrade procedure.
  • Toolkit profiles can simplify repeated connections; direct invocation gives you more explicit control over arguments and environment variables.

Or skip the browser setup

If your actual task is collecting screenshots for an AI agent, you can use ScreenshotNeo instead of assembling a browser container and MCP wiring. ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. The MCP server lets Claude, Cursor, and other MCP clients call screenshot, page-info, and PDF tools. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Is an MCP server from Docker Hub remote?

The direct configuration runs the image locally as a subprocess of your MCP client. A hosted MCP endpoint uses a different transport and configuration.

Do I need a Hub PAT for public searches?

No. The documented Docker Hub server can query public content without the optional PAT. Private repositories and management operations require authentication.

Should I use Toolkit or docker run?

Use direct invocation for a known image and explicit client configuration. Use Toolkit for catalog discovery, profiles, and managed client connections.

Can I use any Docker image as an MCP server?

Only if the image implements MCP and exposes a transport your client supports. A normal web or command-line image is not automatically an MCP server.

Why does the container need -i?

It keeps standard input open so the client can exchange MCP messages over stdio.

Keep reading