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
- 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
Assessment
This issue has not been assessed yet.