Claude Code Environment Variables: Complete Guide

Claude Code Environment Variables: Complete Guide

Many developers using Claude Code eventually need to work with environment variables. Whether you're configuring API keys, authenticating MCP servers, or passing values to scripts and development tools, understanding how Claude Code handles environment variables is essential.

Unlike traditional applications that rely on a single configuration file, Claude Code supports environment variables through multiple configuration layers. Depending on your use case, variables may be defined globally, shared with your team, kept local to your machine, or supplied directly to individual MCP servers.

Choosing the correct location matters. Storing sensitive values in the wrong file can accidentally expose secrets through version control, while defining variables at the wrong scope may cause projects to behave differently than expected.

In this guide, you'll learn:

• what Claude Code environment variables are
• where environment variables can be defined
• the difference between global, project, and local variables
• how environment variables work with MCP servers
• configuration precedence
• security best practices for protecting secrets

By the end of this guide, you'll know exactly where environment variables belong, how Claude Code applies them, and how to structure your configuration for both personal projects and team environments.

Quick answer: Claude Code supports environment variables through its layered configuration system. Variables may be defined in user settings, project settings, local project settings, or within .mcp.json for individual MCP servers. Choosing the correct scope helps keep configuration secure, portable, and easy to maintain.

What Are Claude Code Environment Variables?

Environment variables are key-value pairs that provide configuration values to applications without hardcoding them into source code.

Instead of embedding sensitive information such as API keys, access tokens, database credentials, or service endpoints directly inside your project, developers typically store these values as environment variables. This approach improves security, makes configuration easier to manage across different environments, and allows the same codebase to be used in development, testing, and production.

Claude Code uses environment variables in several ways. Depending on your workflow, they may be used to:

• authenticate with external services
• provide credentials to MCP servers
• configure custom scripts
• control development environments
• supply values required by external tools

Unlike application-specific settings, environment variables usually represent information that changes between machines or environments rather than changing how Claude Code itself behaves.

For example, two developers may work on the same repository while using different API keys. Instead of modifying shared configuration files, each developer can provide their own environment variables locally.

This separation helps keep repositories portable while reducing the risk of accidentally exposing sensitive credentials through version control.

Where Can You Define Environment Variables?

Claude Code supports multiple configuration scopes, allowing environment variables to be defined at the level that best matches their intended use.

Some variables should be available across every project you work on, while others belong only to a single repository or even a single MCP server. Understanding these scopes helps prevent configuration conflicts and keeps sensitive information in the appropriate location.

The most common locations are:

Each configuration file serves a different purpose.

Choosing the correct location improves security, avoids unnecessary duplication, and ensures environment variables are available exactly where they are needed.

~/.claude/settings.json

The global settings file is intended for configuration that should apply to every Claude Code project on your machine.

This is an appropriate location for personal configuration that remains consistent across repositories. Examples include developer-specific preferences or credentials that are required regardless of which project you are currently working on.

Because this file lives inside your home directory, it belongs only to your workstation and should never be treated as shared project configuration.

.claude/settings.json

Project settings are shared with the entire development team.

When environment variables are genuinely required by every contributor, they can be defined as part of the project's shared configuration so everyone works with the same baseline.

However, sensitive credentials generally should not be committed to version control. Shared project configuration is better suited for non-secret values or references to variables that developers provide locally.

.claude/settings.local.json

Some environment variables are needed only by a single developer.

For example, you might use a personal API key, connect to a private testing service, or temporarily override a configuration while debugging.

These values belong in settings.local.json, allowing you to customize your local environment without affecting other contributors or creating unnecessary Git changes.

.mcp.json

The .mcp.json file has a different responsibility.

Instead of configuring Claude Code itself, it defines the MCP servers available to the project. Many MCP servers require credentials, service URLs, or other runtime values, making environment variables an important part of their configuration.

Keeping server-specific variables alongside the MCP server definition helps isolate integration details from Claude Code's general configuration while making projects easier to understand and maintain.

How Claude Code Uses Environment Variables

Environment variables are not limited to storing secrets. They provide a flexible way to supply runtime configuration to Claude Code, MCP servers, and the external tools used throughout your development workflow.

Rather than hardcoding values into configuration files or application code, environment variables allow the same project to behave differently depending on where it is running.

Common use cases include:

• API authentication
• database connection details
• cloud service credentials
• development and testing environments
• custom scripts
• MCP server configuration

For example, a project may require access to a GitHub API, an internal company service, or a third-party AI provider. Instead of committing credentials to the repository, each developer supplies their own environment variables while the project configuration remains identical.

This separation improves security, simplifies onboarding, and makes repositories easier to share without exposing sensitive information.

Why Environment Variables Are Better Than Hardcoding Secrets

Hardcoding credentials directly into source code makes projects more difficult to maintain and significantly increases the risk of accidentally exposing sensitive information.

Environment variables separate configuration from application code, allowing the same project to run in different environments without modifying the codebase itself.

This approach provides several advantages:

• credentials are not embedded in source code
• API keys can be rotated without code changes
• development, staging, and production environments can use different values
• teams can share the same repository while using individual credentials
• configuration remains portable across machines

Using environment variables is a widely adopted software engineering practice and is recommended for nearly every project that depends on external services or sensitive credentials.

Global vs Project Environment Variables

One of the most important decisions is determining where an environment variable belongs.

As a general rule, the broader the intended audience, the broader the configuration scope.

Global Variables

Global variables are available across every Claude Code project on your machine.

Typical examples include:

• personal API credentials
• developer-specific preferences
• workstation-wide configuration
• values reused across multiple repositories

These variables are stored in your user configuration and remain private to your machine.

Project Variables

Project variables are associated with a specific repository.

They are useful when every contributor needs the same non-sensitive configuration, such as service endpoints, feature flags, or shared project defaults.

If a value differs between developers or contains sensitive information, it generally should not be committed as part of the shared project configuration.

Local Project Variables

Some values belong only to a single developer working on a single project.

Examples include:

• personal testing credentials
• temporary development overrides
• local debugging configuration
• experimental integrations

Keeping these variables inside local project settings prevents unnecessary Git changes while allowing every developer to customize their own environment independently.

Environment Variables for MCP Servers

Many MCP servers require additional configuration before they can communicate with external services.

Rather than embedding credentials directly inside server implementations, environment variables are commonly used to provide runtime values such as API keys, access tokens, service URLs, or authentication credentials.

For example, an MCP server that integrates with GitHub may require a personal access token, while another server might connect to an internal company API using organization-specific credentials.

Keeping these values outside application code provides several advantages:

• credentials can be rotated without changing source code
• different developers can use different accounts
• production and development environments remain independent
• secrets are less likely to be committed to Git

This approach follows standard software engineering practices and keeps MCP integrations portable across different environments.

Environment Variable Precedence

Environment variables follow the same layered philosophy as the rest of Claude Code's configuration.

Claude Code organizes configuration using multiple scopes. In practice, broader configuration provides reusable defaults, while more specific configuration is typically used to customize individual projects and MCP servers.

flowchart TD

A[Global Configuration]

B[Project Configuration]

C[Local Project Configuration]

D[MCP Server Configuration]

E[Effective Runtime Configuration]

A --> B
B --> C
C --> D
D --> E

This hierarchy allows developers to define sensible global defaults while still customizing individual projects and MCP integrations without affecting unrelated repositories.

When troubleshooting unexpected behavior, always verify whether a variable is being overridden by a more specific configuration source.

Configuration Examples

The exact structure of configuration files may evolve as Claude Code continues to develop. Rather than relying on implementation details, it is more useful to understand which configuration scope should be used for different types of values.

Global Configuration

Location

~/.claude/settings.json

Typical use cases

• personal developer preferences
• workstation-wide defaults
• configuration shared across all projects

This scope is intended for values that belong to you rather than to a specific repository.

Shared Project Configuration

Location

.claude/settings.json

Typical use cases

• project-wide defaults
• shared development configuration
• settings used by the entire team

Only non-sensitive configuration should be shared with every contributor.

Local Project Configuration

Location

.claude/settings.local.json

Typical use cases

• personal API credentials
• temporary testing configuration
• local debugging preferences

This file allows every developer to customize their own environment without modifying shared project settings.

MCP Server Configuration

Unlike general Claude Code configuration, MCP servers explicitly support environment variables as part of their server definition.

Example:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Security Best Practices

Environment variables often contain sensitive information, making them one of the most important parts of your Claude Code configuration from a security perspective.

Following a few simple practices can significantly reduce the risk of accidentally exposing credentials.

Never Commit Secrets

API keys, access tokens, passwords, and private credentials should never be committed to a Git repository.

Even private repositories can eventually become public, be shared with contractors, or expose historical commits.

Whenever possible, keep secrets outside version-controlled configuration.

Use the Smallest Possible Scope

Not every environment variable needs to be available everywhere.

Ask yourself:

• Does every project need this value?
• Does every developer need it?
• Does only one MCP server use it?

Choosing the smallest appropriate scope makes configuration easier to understand and limits the impact of mistakes.

Rotate Credentials Regularly

Environment variables are not permanent.

API keys and tokens should be rotated periodically, especially after:

• employee offboarding
• suspected credential exposure
• repository leaks
• security incidents

Regular credential rotation reduces the impact of accidental disclosure.

Avoid Reusing Production Credentials

Development, staging, and production environments should use separate credentials whenever possible.

Using dedicated development credentials limits the consequences of accidental changes and makes testing much safer.

Document Required Variables

Projects that depend on environment variables should clearly document which values are required.

Instead of publishing secrets, provide a simple list of required variable names together with a brief explanation of their purpose.

Good documentation makes onboarding easier while keeping sensitive values private.

Common Mistakes

Most problems involving Claude Code environment variables are caused by configuration mistakes rather than software bugs.

Understanding the most common pitfalls can save considerable debugging time.

Storing Secrets in Git

One of the most common mistakes is committing API keys or access tokens directly into project configuration.

Even if the repository is private today, credentials should always be treated as sensitive information.

Using the Wrong Configuration Scope

Developers sometimes place project-specific variables in their global configuration or store personal credentials inside shared project settings.

Keeping variables in the correct scope makes configuration easier to maintain and prevents unexpected behavior across projects.

Mixing Claude Code Configuration with MCP Configuration

Claude Code settings and MCP server configuration serve different purposes.

General Claude Code behavior belongs in settings.json, while server-specific runtime configuration belongs with the MCP server definition inside .mcp.json.

Keeping these responsibilities separate results in cleaner, easier-to-maintain projects.

Assuming Every Developer Uses the Same Environment

Different developers often use different operating systems, credentials, cloud accounts, or local development environments.

Configuration should be flexible enough to support these differences without requiring modifications to shared project files.

Conclusion

Understanding how Claude Code environment variables work helps you build development environments that are more secure, easier to maintain, and simpler to share across projects and teams.

Rather than relying on a single configuration file, Claude Code uses a layered configuration system that allows environment variables to be managed at different scopes. Global settings provide machine-wide defaults, project settings establish shared team configuration, local settings support personal customization, and .mcp.json enables individual MCP servers to receive the runtime values they need.

Choosing the correct scope is just as important as choosing the correct variable. Keeping shared configuration separate from personal settings reduces merge conflicts, while storing secrets outside version-controlled files helps protect sensitive credentials and simplifies credential rotation.

Whether you're configuring API keys for personal development, sharing project defaults with your team, or deploying MCP servers that depend on external services, organizing environment variables correctly will make your Claude Code setup more secure, predictable, and easier to maintain.

Continue learning:

• Claude Code config.json — Understand how settings.json files and Claude Code configuration work.
• Claude Code MCP Permissions — Learn how permission rules and approval workflows work.
• Claude Code Environment Variables — Configure environment variables securely for Claude Code and MCP servers.