Windows: Docker MCP Gateway fails to connect to Claude Desktop (multiple issues and workaround)

[ViniciusMRod]

Issue summary

This issue is a usage/compatibility report on Windows (no code changes), with logs and a working configuration so maintainers can decide whether to address this in code or documentation.

On Windows, Docker MCP Gateway fails to connect to Claude Desktop in several scenarios.
This issue documents three related problems and a working configuration, so maintainers can decide what should be fixed in code vs. documented as known limitations.

Affected versions:

• Windows 11
• Docker Desktop 4.62 (MCP Toolkit enabled)
• Claude Desktop (official .exe installer, not Microsoft Store)
• docker-mcp plugin v0.40.0

Fix: Docker MCP Toolkit not connecting to Claude Desktop on Windows

TL;DR: Two separate bugs can prevent Docker MCP Toolkit from connecting to Claude Desktop on Windows. This post covers both, in the order you'll likely hit them.

---

The symptoms

• Claude Desktop shows MCP_DOCKER as "failed" or "Server disconnected"
• The Docker MCP Toolkit web interface shows your servers as configured and enabled
• Running docker mcp gateway run manually works fine in your terminal
• You've already restarted everything multiple times 😅

---

Bug #1 — Microsoft Store version of Claude Desktop

If you installed Claude Desktop from the Microsoft Store, uninstall it. The Store version runs in a sandboxed environment that doesn't allow proper access to configuration files and MCP integrations.

Fix: Download and install the official .exe installer directly from claude.ai/download.

After installing, your config file will be located at:

%APPDATA%\Claude\claude_desktop_config.json

(which expands to C:\Users\YOUR_USERNAME\AppData\Roaming\Claude\claude_desktop_config.json)

---

Bug #2 — Claude Desktop can't find the Docker MCP plugin

Even with the correct Claude Desktop version, you'll likely hit this error in your logs:

docker: unknown command: docker mcp
Run 'docker --help' for more information

Why it happens: Claude Desktop tries to run docker mcp gateway run, but the Docker CLI doesn't find the MCP plugin because it's not in the expected PATH.

The plugin lives at:

C:\Program Files\Docker\cli-plugins\docker-mcp.exe

Fix: In your claude_desktop_config.json, point directly to the .exe instead of relying on the docker CLI to find it:

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "C:\\Program Files\\Docker\\cli-plugins\\docker-mcp.exe",
      "args": ["gateway", "run"]
    }
  }
}

---

Bug #3 — panic: unable to get 'ProgramData'

If you check your logs (Settings → Developer → Ver Logs) and see this:

panic: unable to get 'ProgramData' [recovered, repanicked]
github.com/docker/mcp-gateway/pkg/desktop.init.func1()
    github.com/docker/mcp-gateway/pkg/desktop/paths.go:17

Why it happens: Claude Desktop doesn't pass standard Windows environment variables to child processes. The docker-mcp.exe binary needs ProgramData to locate Docker Desktop's socket and configuration.

Fix: Add the missing environment variables explicitly in your config:

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "C:\\Program Files\\Docker\\cli-plugins\\docker-mcp.exe",
      "args": ["gateway", "run"],
      "env": {
        "ProgramData": "C:\\ProgramData",
        "LOCALAPPDATA": "C:\\Users\\YOUR_USERNAME\\AppData\\Local",
        "APPDATA": "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming",
        "USERPROFILE": "C:\\Users\\YOUR_USERNAME",
        "SystemRoot": "C:\\Windows"
      }
    }
  }
}

⚠️ Replace YOUR_USERNAME with your actual Windows username.

Save the file, restart Claude Desktop, and the status should change to running 🟢

---

How to check your logs

1. Open Claude Desktop
2. Go to Settings → Developer
3. Click "Ver Logs" (or "View Logs") next to MCP_DOCKER
4. Look for the error messages described above

---

Environment tested

• Windows 11
• Docker Desktop 4.62 with MCP Toolkit enabled (Settings → Beta Features)
• Claude Desktop installed via official .exe (not Microsoft Store)
• docker-mcp plugin v0.40.0

---

References

• Docker MCP Toolkit docs
• MCP debugging guide
• Similar issue reported: docker/for-win#14860

---

Hope this saves someone a few hours of frustration! If it worked for you, drop a comment below 🙌

What I would expect / Possible improvements

• Either:
  • Make docker-mcp more robust when common Windows env vars (like ProgramData) are missing, or
  • Document the required env vars and example config for Claude Desktop on Windows.
• Consider adding a short “Windows troubleshooting” section to the README or docs.
• Optionally warn users about the Microsoft Store version of Claude Desktop in the docs.

[gregnm369]

Your workaround works but I'm running into a couple of issues:

1. Docker Desktop does not recognize the link between Claude Desktop and Docker when using this method. Claude Desktop does see the MCP_DOCKER connection, however.

2. While Claude Desktop can see and call upon Docker with this integration, it can not access secrets properly. I use the Claude Desktop/Docker MCP Toolkit/Obsidian Local REST API combination - and now, Claude Desktop can not recognize the API key from Docker's secrets with this method.