charmbracelet/crush · error

docker mcp is not available, please ensure docker is install

Error message

docker mcp is not available, please ensure docker is installed and 'docker mcp version' succeeds

What it means

Returned by ConfigStore.PrepareDockerMCPConfig when IsDockerMCPAvailable() reports that Docker MCP is not usable on this machine. Availability requires the Docker CLI to be installed and `docker mcp version` to succeed — i.e. Docker with the MCP Toolkit feature present and working.

Source

Thrown at internal/config/docker_mcp.go:87

	_, exists := c.MCP[DockerMCPName]
	return exists
}

// DockerMCPConfig returns the default Docker MCP stdio configuration.
func DockerMCPConfig() MCPConfig {
	return MCPConfig{
		Type:     MCPStdio,
		Command:  "docker",
		Args:     []string{"mcp", "gateway", "run"},
		Disabled: false,
	}
}

// PrepareDockerMCPConfig validates Docker MCP availability and stages the
// Docker MCP configuration in memory.
func (s *ConfigStore) PrepareDockerMCPConfig() (MCPConfig, error) {
	if !IsDockerMCPAvailable() {
		return MCPConfig{}, fmt.Errorf("docker mcp is not available, please ensure docker is installed and 'docker mcp version' succeeds")
	}

	mcpConfig := DockerMCPConfig()
	// In-memory only; persistence happens in PersistDockerMCPConfig.
	s.mutateInMemory(func(c *Config) {
		if c.MCP == nil {
			c.MCP = make(map[string]MCPConfig)
		}
		c.MCP[DockerMCPName] = mcpConfig
	})
	return mcpConfig, nil
}

// PersistDockerMCPConfig persists a previously prepared Docker MCP
// configuration to the global config file.
func (s *ConfigStore) PersistDockerMCPConfig(mcpConfig MCPConfig) error {
	if err := s.SetConfigField(ScopeGlobal, "mcp."+DockerMCPName, mcpConfig); err != nil {
		return fmt.Errorf("failed to persist docker mcp configuration: %w", err)

View on GitHub (pinned to 7944b8e522)

Solutions

1. Install or update Docker Desktop (or the docker-mcp CLI plugin) to a version that supports `docker mcp`.
2. Run `docker mcp version` manually to reproduce and diagnose the underlying failure.
3. Start the Docker daemon (Docker Desktop running / systemctl start docker) and retry.
4. If Docker MCP is not wanted, skip enabling it — this error only blocks the Docker MCP integration.

Example fix

// before
$ docker mcp version
docker: 'mcp' is not a docker command. // old Docker
// after
$ # update Docker Desktop to >= 4.43 (or install docker-mcp plugin), then:
$ docker mcp version
Docker MCP version vX.Y.Z

cmd := exec.Command("docker", "mcp", "version")
if err := cmd.Run(); err != nil {
    return errors.New("docker MCP unavailable: install/update Docker Desktop or the docker-mcp plugin first")
}

func dockerMCPAvailable() bool {
    out, err := exec.Command("docker", "mcp", "version").Output()
    return err == nil && len(out) > 0
}

if err := store.EnableDockerMCP(); err != nil {
    if strings.Contains(err.Error(), "docker mcp is not available") {
        showInstallInstructions("https://docs.docker.com/desktop/")
        return nil // degrade gracefully, skip Docker MCP feature
    }
    return err
}

When it happens

Trigger: Enabling Docker MCP (via EnableDockerMCP / `docker mcp` enable flow in the UI) when Docker is not installed, the Docker daemon/CLI is too old to include the `mcp` subcommand, or `docker mcp version` fails (daemon not running, plugin missing).

Common situations: Docker Desktop without MCP Toolkit enabled; plain docker Engine (Linux) lacking the docker-mcp plugin; Docker not installed at all; daemon stopped; older Docker Desktop version predating `docker mcp`.

Related errors

• ripgrep not found in $PATH
• failed to start docker MCP: %w
• docker MCP started but failed to persist configuration: %w
• failed to disable docker MCP: %w
• failed to enable docker MCP: %w

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/ace46772280850c6. Report an issue: GitHub.