Environment secrets and version control for claude_desktop_config.json

[g-simmons]

Question

I am looking for suggestions for how to version my claude_desktop_config.json without committing secrets.

More details

Background

Like many of you, I like to version control my dotfiles. I consider claude_desktop_config.json to be a dotfile.

My dotfiles are not publicly accessible, but maybe they will be one day. I prefer not to include secrets in my dotfiles.

Some servers that I have seen (ex) require that secrets be included in claude_desktop_config.json. To my knowledge, the secrets need to be included verbatim. Please correct me if that's not true. I am getting my info from this part of the docs.

Possible solutions

One solution would be to version control a template, and build claude_desktop_config.json from claude_desktop_config.json.template. If anyone has already done this I would be curious to see how you did it :)

If there are other ways to get specific variables & values from my default shell environment into my servers, that would be nice to know about :).

Potentially confusing part of the docs

The docs state:

To override the default variables or provide your own, you can specify an env key in claude_desktop_config.json:

{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}

Someone could interpret this to mean that "some_key" can be a key, like "GITHUB_TOKEN". That would actually be quite convenient. But example configuration for several servers suggests that it should be a value, like an actual GitHub token string. Examples:

Github Server:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ]
    },
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
    }
  }

}

Brave Search:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

I've confirmed that setting "some_key" to an environment key does not work with the following test:

in my shell:

export BRAVE_API_KEY=<my-actual-key-string>

claude_desktop_config.json

...
"brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "BRAVE_API_KEY"
      }
    },
...

Quit & Restart Claude Desktop

Result:

Brave search works again if I set

 "env": {
        "BRAVE_API_KEY": "theactualkeystring"
      }

Pre-submission Checklist

• I have checked that this question would not be more appropriate as an issue in a specific repository
• I have searched existing discussions and documentation for answers

Question Category

• Protocol Specification
• SDK Usage
• Server Implementation
• General Implementation
• Documentation
• Other

[g-simmons]

I will be doing this for now:

#!/bin/bash
cat claude_desktop_config.json.template \
  | sed -E "s/:\s*\"(BRAVE_API_KEY)\"/:\"$BRAVE_API_KEY\"/g" \
  > claude_desktop_config.json

But I am still curious to see other answers :)

[adamavenir]

You might try 1Password as a pretty good UX option for this. You can do:

AWS_ACCESS_KEY_ID="op://development/aws/Access Keys/access_key_id"
AWS_SECRET_ACCESS_KEY="op://development/aws/Access Keys/secret_access_key"

and

MYSQL_DATABASE = "op://$APP_ENV/mysql/database"
MYSQL_USERNAME = "op://$APP_ENV/mysql/username"
MYSQL_PASSWORD = "op://$APP_ENV/mysql/password"

See docs here

[g-simmons]

Thanks for this, I wasn't aware that 1Password had this level of developer support.

[pythoninthegrass]

fwiw I hacked together a solution using ~/.bash_aliases and envsubst:

# ~/.bash_aliases

# claude
# * NOTE: requires `envsubst` (from `gettext` package)
if [[ -f "$HOME/git/claude_config/.env" ]]; then
    export $(grep -v '^#' "$HOME/git/claude_config/.env" | xargs)
    envsubst < "$HOME/git/claude_config/claude_desktop_config.json.tpl" \
        > "$HOME/git/claude_config/claude_desktop_config.json"
fi

then in my git repo ~/git/claude_config it has an .env file that interpolates variables in claude_desktop_config.json.tpl to claude_desktop_config.json which are then symlinked to the regular ~/.claude counterparts.

In the repo my .gitignore looks like this:

claude_desktop_config.json
!claude_desktop_config.json.tpl