Where Is the Claude Code settings.json File Located?

Your personal Claude Code settings file is located at ~/.claude/settings.json. Each project can also have its own .claude/settings.json and .claude/settings.local.json files inside the project folder.

Claude Code reads all of these files and combines them, so knowing which one to edit matters.

This article covers every settings file location, which file wins when they conflict, and where MCP server configurations are saved (hint: not in settings.json).

The settings.json locations

Claude Code reads settings from four places:

The ~/.claude path is the .claude folder in your home directory. The bare .claude path is a folder inside your project.

Here are the full user settings paths for each operating system:

Why can’t I find my settings.json?

Installing Claude Code doesn’t create any settings file. That’s why the file may be missing when you look for it.

Claude Code creates the files the first time it needs them:

• ~/.claude/settings.json is created when you change an option in the /config menu, such as the theme
• .claude/settings.local.json is created when you approve a permission prompt with “Yes, and don’t ask again”

You can also create the file yourself. On macOS or Linux:

mkdir -p ~/.claude
touch ~/.claude/settings.json

Then add your settings as JSON. Here’s an example that allows lint and test commands without asking and blocks reading .env files:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

The $schema line is optional, but it gives you autocomplete and validation in VS Code and Cursor.

The file must be strict JSON. A // comment or a trailing comma will cause a “Settings Error” the next time you start Claude Code.

Which settings file wins?

When the same setting appears in more than one file, Claude Code uses this order, from highest to lowest priority:

1. Managed settings (your organization)
2. Command line flags like --settings
3. Project local: .claude/settings.local.json
4. Shared project: .claude/settings.json
5. User: ~/.claude/settings.json

So if your team’s .claude/settings.json sets a value you don’t like, put your own value in .claude/settings.local.json. It overrides the shared file only for you.

List settings like permissions.allow are different: Claude Code merges the lists from every file instead of picking one.

How to check which files were loaded

Run /status inside Claude Code. The Setting sources line lists every settings file loaded for the current session.

If you suspect a broken file, run this from your terminal:

claude doctor

It validates your settings files and reports any entry Claude Code rejected.

Where is the managed settings file?

If your company manages Claude Code, the managed-settings.json file is stored in a system folder:

You can’t override these settings from your own files. Managed settings can also be delivered from the claude.ai admin console, in which case there may be no file on your disk at all.

Where is the MCP server config stored?

MCP servers are not saved in settings.json. They’re stored in two other files:

• ~/.claude.json holds your personal MCP servers (user and local scope), along with your account details and per-project state
• .mcp.json in your project root holds MCP servers shared with your team

Note that ~/.claude.json is a file in your home directory, not inside the ~/.claude/ folder. Claude Code writes it for you, so you usually manage it with commands like claude mcp add instead of editing it by hand.

Where is the API key stored?

Claude Code doesn’t store your login in settings.json.

On macOS, your credentials are stored in the encrypted macOS Keychain. On Linux and Windows, they’re stored in ~/.claude/.credentials.json. If you use an API key, it’s usually read from the ANTHROPIC_API_KEY environment variable.

Never commit any of these files to git.

Conclusion

Your personal settings are in ~/.claude/settings.json, project settings are in .claude/settings.json, and your private project overrides are in .claude/settings.local.json.

If the file doesn’t exist yet, create it. And if a setting doesn’t seem to apply, run /status to see which files were loaded.

For other files Claude Code keeps in ~/.claude, see where Claude Code sessions are stored and where Claude Code skills are stored.