google-gemini / google-gemini/gemini-cli

[Bug][MCP] {{HOME}} template variable silently ignored in mcpServers config — causes ALL MCPs to show Disconnected with zero error output

Open
#26,166 2 comments 0 reactions 0 assignees View on GitHub
area/documentation kind/enhancement priority/p3 Stale status/bot-triaged
Dominant language
TypeScript
Stars
107k
Forks
14.6k
Avg merge
2d 3h
Merged PRs (30d)
45

Description

## 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
```json
{
"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
```bash
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:
```bash
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:

| Behavior | Detail |
|---|---|
| Error visibility | ❌ None — shows only "Disconnected" |
| Debug hint | ❌ None — no log, no stderr output |
| Documentation | ❌ Community examples use `{{HOME}}` syntax |
| Blast radius | 🔴 All MCP servers fail simultaneously |
| Time to discover | Took 1 user approximately **6 weeks** to find |

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)

```bash
# 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:

```typescript
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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.