Gemini CLI is not performing environment variable substitution for MCP Servers

[DinoChiesa]

What happened?

Summary

I am using the github-mcp-server, the official one from Microsoft. I am seeing some confusing behavior with the way Gemini CLI treats environment variables. I think this is not relevant to the specific MCP Server.

Case 1: explicit secret in the settings file - WORKS

This configuration in settings.json , in which I explicitly specify the value for the personal access token, "works" The token is applied by the MCP server.:

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
    "github-stdio": {
      "command": "github-mcp-server",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_BISAMPLEKEYp"
      },
      "trust": true
    }
  },
   ...
}

Case 2: implicit reference to .env environment variables - WORKS

In this case, GITHUB_PERSONAL_ACCESS_TOKEN is defined in my ~/.gemini/.env file with the correct value.

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
    "github-stdio": {
      "command": "github-mcp-server",
      "args": ["stdio"],
      "trust": true
    }
  },
   ...
}

Case 3: environment variable substitution - DOES NOT WORK

Here as above, GITHUB_PERSONAL_ACCESS_TOKEN is defined in my ~/.gemini/.env file . But in this case the MCP server does not work; every call fails with 401 Bad Credentials. The reason I would want to do this, rather than relying on the magic/silent environment variables as in Case 2, is to "document" which env variables are needed by this particular server.

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
    "github-stdio": {
      "command": "github-mcp-server",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      },
      "trust": true
    }
  },
   ...
}

Further details

Same is true if I use the docker/podman version of the MCP server.

Suggestion

Maybe the problem is that I am using the same name for the input and output of the environment variable.
I don't know, I grew weary of testing all these scenarios.

But it seems like something is not working correctly.

This may be related to #5282 . But note in the above - none of these are remote servers. I am not using HTTP headers.

What did you expect to happen?

I expect that substitution of env variables works for local MCP servers, even if the environment variable names are the same.

Client information

╭──────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                      │
│ About Gemini CLI                                                                                     │
│                                                                                                      │
│ CLI Version                        0.1.17                                                            │
│ Git Commit                         b3cfaeb6                                                          │
│ Model                              gemini-2.5-pro                                                    │
│ Sandbox                            no sandbox                                                        │
│ OS                                 linux                                                             │
│ Auth Method                        OAuth                                                             │
│ GCP Project                        my-gca-3201                                                     │
│                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯```

</details>


### Login information

Google Account

### Anything else we need to know?

_No response_

[Manamama]

My unrelated tip: avoid trust there like a plague. See: #5512 of mine.

[jackwotherspoon]

@Manamama this issue has nothing to do with trust from the looks of it.

I think this may be related to #5605 in the order of operations in which loadSettings and loadEnvironment are called.

[jackwotherspoon]

The following configuration works for me...

{
  "selectedAuthType": "gemini-api-key",
  "theme": "Default",
  "preferredEditor": "windsurf",
  "mcpServers": {
    "github": {
      "httpUrl": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "${GITHUB_PAT}"
      }
    }
  }
}

[DinoChiesa]

Yes, it works if the environment variables are defined in the .env file. (See my case 2) But not if I explicitly refer to them, and the names are the same as those used in the .env file. (case 3)

[leehagoodjames]

@jackwotherspoon that config works for me, but the gemini-cli docs recommended show connecting to the GitHub MCP with:

    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    }

Unfortunately it is very unclear with the errors why this doesn't work. Should we update our GitHub MCP tutorial?

[leehagoodjames]

@DinoChiesa one of the frustrating things is that I need to run source ~/.gemini/.env to get Gemini to use the keys in that file, indicating that they aren't loaded by running the gemini command and gemini just uses what exists already in the shell.

This may be causing the env variable substitution to not work as expected

[DinoChiesa]

@leehagoodjames FYI, Specific to github-mcp-server, there is a separate effort, in the github-mcp-server repo, aimed at improving the instructions for configuring it, for Gemini CLI.

[soisyourface]

@jackwotherspoon, i also think this is a duplicate of #5605

@leehagoodjames, that is being remedied by #5605 and corresponding PR.