Environment

• OS: Windows 10 Host / Ubuntu 24.04 (WSL2)
• Gemini CLI: v0.40.0
• Shell: bash (WSL2)
• Settings file: ~/.gemini/settings.json

Summary

Gemini CLI v0.40.0 silently ignores the {{HOME}} template variable in mcpServers configuration. The string is passed verbatim to the process spawner, causing every MCP server to fail with no error output — reported to the user only as "Disconnected".

This caused weeks of misdirected debugging because the failure surface gave no indication that the root cause was an unresolved path template.

Reproduction

Step 1: Configure any MCP server using {{HOME}} syntax

{
  "mcpServers": {
    "github": {
      "command": "{{HOME}}/.bun/bin/bun",
      "args": ["{{HOME}}/.npm-global/lib/node_modules/@modelcontextprotocol/server-github/dist/index.js"]
    }
  }
}

Step 2: Launch Gemini CLI

gemini

Step 3: Check MCP status

/mcp list
→ 🔴 github - Disconnected

No error message is shown. No log output. No hint that the path failed.

Root Cause

Searched the entire bundled source:

grep -c '{{' ~/.npm-global/lib/node_modules/@google/gemini-cli/bundle/gemini.js
# Output: 0

Zero occurrences. The {{HOME}} expansion logic does not exist in the Gemini CLI codebase. The raw string {{HOME}}/.bun/bin/bun is passed to child_process.spawn(), which fails because no such path exists.

The Node.js child_process does not expand shell variables or template strings — it requires a literal, resolved path.

Impact

This is a silent, undiscoverable failure with maximum user impact:

The failure is particularly insidious because:

1. Gemini CLI correctly reads the settings file (it shows "12 MCP servers configured")
2. It correctly counts the MCPs in the UI footer
3. It silently fails to spawn them without any diagnostic output
4. Users debug network issues, permissions, and bun versions — never suspecting the path template

Fix (User-side Workaround)

# Replace all {{HOME}} with actual home directory
sed -i "s|{{HOME}}|$HOME|g" ~/.gemini/settings.json

After this single substitution: all MCP servers connected immediately on next launch.

Requested Changes

Option A: Implement {{HOME}} expansion (recommended)

Before spawning MCP server processes, resolve {{HOME}} (and potentially other template variables like {{USER}}, {{PWD}}) in the command and args fields:

const resolveTemplate = (s: string): string =>
  s.replace(/\{\{HOME\}\}/g, os.homedir())
   .replace(/\{\{USER\}\}/g, os.userInfo().username);

const resolvedCommand = resolveTemplate(serverConfig.command);
const resolvedArgs = serverConfig.args.map(resolveTemplate);

Option B: Warn on unresolved templates

If template expansion is intentionally not supported, the CLI should detect {{...}} patterns in command/args paths and emit a clear warning:

⚠️  MCP server "github": command contains unresolved template "{{HOME}}".
    Replace with absolute path: /home/username/.bun/bin/bun

Option C: Document the limitation

At minimum, add a clear note to the MCP configuration documentation that {{HOME}} and similar template variables are not supported and will cause silent failures.

Related Issues

• #26164 — Model self-diagnosis failure (this bug is the root cause documented there)
• #26114 — Large paste premature execution
• #26117 — Comprehensive reliability failure report