Claude Code Config File Location and Settings

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

TL;DR: Global settings live at ~/.claude/settings.json. Project settings at .claude/settings.json in your repo root. MCP servers are configured separately in ~/.claude.json (user scope) or .mcp.json (project scope).

The Problem

You need to customize Claude Code’s behavior but are unsure where configuration files are stored, or your changes to settings are not taking effect.

Why This Happens

Claude Code uses a layered configuration system with multiple file locations. Settings are merged in order of precedence, and changes to the wrong file may be overridden by a higher-priority source.

The Fix

Step 1 — Understand the Configuration Hierarchy

Claude Code reads settings from these locations, in order of precedence (highest first):

Priority Location Scope
1 CLI flags Current session only
2 ~/.claude/settings.local.json Local (machine-specific, not committed)
3 .claude/settings.json Project (committed to repo)
4 ~/.claude/settings.json User (all projects)

Note: Enterprise deployments may also have a “Managed” policy layer that sits above CLI flags and cannot be overridden by users.

Step 2 — Find Your Config Files

# User settings (applies to all projects)
ls -la ~/.claude/settings.json

# Local settings (machine-specific overrides, not committed)
ls -la ~/.claude/settings.local.json

# Project settings (from your repo root, committed to version control)
ls -la .claude/settings.json

# MCP server config — user scope
ls -la ~/.claude.json

# MCP server config — project scope
ls -la .mcp.json

# Memory files
ls -la ~/.claude/CLAUDE.md
ls -la CLAUDE.md

# Credentials (macOS uses Keychain, Linux uses this file)
ls -la ~/.claude/credentials.json

Step 3 — Edit User Settings

# Create the directory if needed
mkdir -p ~/.claude

# Edit settings
${EDITOR:-nano} ~/.claude/settings.json

Common user settings (~/.claude/settings.json):

{
  "defaultMode": "acceptEdits",
  "skipDangerousModePermissionPrompt": false,
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Read(*)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  },
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": []
  }
}

Valid defaultMode values: default (plan/ask mode), acceptEdits (auto-accept file edits), fullAuto (no prompts).

Step 4 — Edit Project Settings

# From your project root
mkdir -p .claude
${EDITOR:-nano} .claude/settings.json

Common project settings (.claude/settings.json):

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run build)"
    ]
  }
}

Step 5 — Configure MCP Servers

MCP servers are not configured inside settings.json. They have their own dedicated config files:

User-scoped MCP config (~/.claude.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    }
  }
}

Project-scoped MCP config (.mcp.json):

{
  "mcpServers": {
    "project-db": {
      "command": "node",
      "args": ["./tools/mcp-server.js"]
    }
  }
}

Step 6 — Configure Memory Files

Claude Code reads CLAUDE.md files for persistent context:

# Global memory (loaded in every session)
cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Preferences
- I prefer TypeScript over JavaScript
- Always use pnpm as package manager
- Follow NASA Power of 10 coding rules
EOF

# Project memory (loaded when in this project)
cat > CLAUDE.md << 'EOF'
# Project: My App
- This is a Next.js 14 app with App Router
- Database: PostgreSQL via Prisma
- Tests: Vitest + Playwright
EOF

Step 7 — Verify Settings Are Loaded

# Use /config command inside Claude Code to see active settings
claude
> /config

Common Variations

Scenario Cause Quick Fix
Settings not taking effect Wrong file location Check both user and project paths
MCP servers not loading Config placed in settings.json instead of ~/.claude.json or .mcp.json Move MCP config to the correct file
Project MCP servers not found Running Claude from a different directory Use absolute paths in MCP server command args
/config freezes terminal Known bug in v2.1.104 Do not run /config twice; restart session
Settings reset after update npm reinstall overwrites defaults Settings files are not overwritten by updates

Prevention

Last verified: 2026-04-15. Found an issue? Open a GitHub issue.