Use these MCP env template examples to document the environment variables your MCP servers need without exposing real secrets. The goal is to make config setup easier while keeping tokens, database URLs, and API keys out of public pages and commits.
This guide pairs with MCP config JSON examples. The JSON uses placeholders such as ${GITHUB_TOKEN}; the .env.example file explains which private values a developer must provide locally.
The examples below are independent reference templates, not official documentation for any MCP client or server package. Always verify the current server maintainer docs and your client-specific environment loading behavior before using them locally.
Key takeaways
- Commit .env.example, not .env, and keep every value as a placeholder in public examples.
- Group environment variables by MCP server so GitHub, search/browser, and database credentials are easier to review.
- Use least-privilege credentials, rotate demo tokens, and pair env templates with a security checklist before enabling production access.
What belongs in an MCP .env.example file
An MCP .env.example file documents the environment variable names that a local MCP server setup expects. It should show variable names, placeholder values, and short comments about purpose, but it should not contain real tokens, cookies, private URLs, or production credentials.
Use the file as a companion to JSON config examples. The config references placeholders such as ${GITHUB_TOKEN}, while the .env.example tells developers which values they need to define privately on their own machine or secret manager.
- Variable names required by MCP servers
- Safe placeholder values
- Short comments about scope or source
- No real secrets
- No private repository names or internal URLs
Basic MCP .env.example template
Start with only the variables used by the servers you plan to enable. A small file is easier to review than a large list of unused secrets.
The values below are intentionally placeholders. Replace them only in a private local .env file or secret manager, not in a public example.
- Keep names uppercase and descriptive
- Group variables by server
- Use comments for scope notes
- Avoid real tokens in examples
# MCP server environment placeholders
# Copy this file to .env locally, then replace values privately.
GITHUB_TOKEN=your_github_token_here
BRAVE_API_KEY=your_brave_api_key_here
DATABASE_URL=postgres://user:password@localhost:5432/example_dbGitHub MCP env variables
GitHub MCP servers usually need a token or app credential to read repository, issue, pull request, or organization context. Create the narrowest credential that supports the workflow.
For documentation, screenshots, static generators, and shared repos, use placeholders only. Never paste a real GitHub token into a hosted browser form or committed example.
- Prefer read-only scopes first
- Use separate dev and production credentials
- Rotate credentials after demos
- Review write-capable tools separately
# GitHub MCP server
# Use a narrowly scoped token for the local workflow.
GITHUB_TOKEN=your_github_token_here
GITHUB_OWNER=your-org-or-username
GITHUB_REPOSITORY=example-repoSearch and browser MCP env variables
Search and browser MCP servers may need API keys, region settings, timeout values, or browser flags. Keep these tools read-oriented unless you have reviewed prompt-injection and write-action risk.
Because web pages and search results are untrusted content, keep browser/search credentials separate from deployment, database, or GitHub write credentials.
- Use separate API keys for search tools
- Document timeout and headless flags
- Treat web content as untrusted
- Do not mix browsing with destructive credentials
# Search or browser MCP server
BRAVE_API_KEY=your_brave_api_key_here
BROWSER_HEADLESS=true
BROWSER_TIMEOUT_MS=30000Database MCP env variables
Database credentials require extra care. Use a read-only role for exploration, point first tests at a sandbox database, and never publish a real connection string.
If the database server supports schema allowlists, read-only views, or query limits, document those controls next to the environment variables so reviewers understand the safety boundary.
- Use sandbox databases first
- Prefer read-only roles
- Avoid production connection strings
- Document schema or table boundaries
# Database MCP server
DATABASE_URL=postgres://readonly_user:password@localhost:5432/example_db
DATABASE_SCHEMA=public
DATABASE_QUERY_TIMEOUT_MS=10000Claude Desktop config with env placeholders
The JSON config can reference environment placeholder names while the companion .env.example documents what those names mean. Client and server behavior can vary, so confirm how your MCP client provides environment variables to launched server processes.
Use this as a documentation pattern, not as proof that every client automatically loads .env files. Follow the current client and server maintainer docs for the final local setup.
- Keep config JSON and .env.example consistent
- Verify client-specific env loading
- Restart the MCP client after changes
- Test with one server first
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}Team-safe secret handling workflow
For a team, the safest pattern is to commit .env.example, ignore the real .env file, store production values in a secret manager, and document who owns rotation for each credential.
Pair every MCP config change with a quick review: what can the server read, what can it write, where does the data go, and what logs might contain sensitive values?
- Commit .env.example only
- Add .env to .gitignore
- Store production secrets outside Git
- Assign a rotation owner
- Review logs and error redaction
# Safe repository pattern
.env
.env.local
*.pem
*.key
# Commit this instead:
.env.exampleCommon MCP env template mistakes
Most env-template mistakes come from treating examples like real runtime files. Public examples should teach names and shape; private local files hold actual values.
If an MCP server fails after adding env variables, check the exact variable names expected by the server package, confirm the client process can see them, and test the command in a terminal before debugging the assistant.
- Committing real .env files
- Using one broad admin token for everything
- Mismatching env names between config and server docs
- Assuming every client auto-loads .env
- Leaving stale unused secrets enabled
- Printing raw secrets in logs
Implementation checklist
- List only variables used by enabled MCP servers
- Use placeholders in .env.example
- Keep real .env files out of Git
- Match variable names to server maintainer docs
- Use scoped read-only credentials first
- Separate dev and production secrets
- Document rotation owner and schedule
- Redact secrets from logs and error messages
- Verify the MCP client can pass env values to server processes
- Run the MCP security checklist before production use
FAQ
What is an MCP .env.example file?
It is a safe template that lists environment variable names needed by MCP servers, using placeholder values instead of real secrets.
Should I commit my MCP .env file?
No. Commit .env.example if useful, but keep real .env files, tokens, cookies, keys, and production connection strings out of Git.
Can MCP config JSON use environment variables?
Many MCP server examples use env fields or placeholder references, but client behavior can vary. Verify how your MCP client passes environment variables to the launched server process.
What placeholders should public MCP examples use?
Use names such as ${GITHUB_TOKEN}, ${BRAVE_API_KEY}, ${DATABASE_URL}, and ${NOTION_API_KEY}. Do not use real-looking keys or private internal URLs.
How do I make MCP secrets safer for teams?
Use least-privilege credentials, separate dev and production values, store production secrets in a secret manager, assign a rotation owner, and redact logs.
Can a static website safely generate an MCP .env.example template?
Yes, if generation happens entirely in the browser and outputs placeholder values only. It should not collect, validate, store, or upload real secrets.