Claude Code Configuration Files: Complete Guide to Settings, Permissions, MCP Servers & Scopes

Claude Code and Claude Desktop use different configuration systems that can be confusing at first. This guide explains where all configuration files are stored, how permission scopes work, and the critical differences between Claude Code (CLI) and Claude Desktop (app) configurations.

Claude Code vs Claude Desktop: Key Differences

Before diving into configurations, understand that Claude Code (CLI) and Claude Desktop (app) are separate products with different configuration systems:

Main Configuration Directory

Claude Code (CLI) Configuration

All Claude Code configuration lives under:

All Platforms:

~/.claude/

Platform-specific paths:

Claude Desktop Configuration

Claude Desktop stores configuration in platform-specific application directories:

Complete Directory Structure

Here's the full layout of Claude Code's configuration directory:

~/.claude/
├── settings.json           # Global user settings
├── settings.local.json     # Local user settings (not synced)
├── CLAUDE.md               # Global instructions for all projects
├── .credentials.json       # API credentials (Linux/Windows only)
├── statsig/                # Analytics cache
│   └── ...
├── commands/               # Global custom slash commands
│   ├── review.md
│   ├── test.md
│   └── ...
└── projects/               # Session history per project
    ├── -Users-sean-myproject/
    │   ├── session-2025-01-15.jsonl
    │   └── session-2025-01-16.jsonl
    └── -home-user-another-project/
        └── ...

# Project-level files (in your project root)
./
├── CLAUDE.md               # Project-specific instructions
├── CLAUDE.local.md         # Personal project instructions (gitignored)
├── .mcp.json               # Project MCP server configuration
└── .claude/
    ├── settings.json       # Project settings (shared)
    ├── settings.local.json # Project settings (personal)
    └── commands/           # Project-specific slash commands
        └── deploy.md

# User-level MCP configuration (outside .claude directory)
~/.claude.json              # User MCP server configuration

Configuration Files Explained

Settings Files

Claude Code uses a hierarchy of settings files, loaded from least specific to most specific:

Global user settings:

~/.claude/settings.json

Controls default behavior for all projects. Example:

{
  "permissions": {
    "allow": ["Bash(npm run:*)", "Read", "Write"],
    "deny": ["Bash(rm -rf:*)"]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

Local user settings (not synced):

~/.claude/settings.local.json

Personal overrides that shouldn't sync across machines. Add machine-specific paths or credentials here.

Project settings (shared):

.claude/settings.json

Commit this to version control for team-shared configuration.

Project settings (personal):

.claude/settings.local.json

Add to .gitignore for personal project preferences.

Understanding Permission Scopes

This is where most confusion happens. Claude Code has multiple permission scopes that determine what Claude can do:

Permission Scope Hierarchy

Settings and permissions are merged in this order (later entries override earlier):

1. Built-in defaults - Claude Code's safe defaults
2. User settings - ~/.claude/settings.json (applies to ALL projects)
3. Project settings - .claude/settings.json (shared with team via git)
4. Local overrides - .claude/settings.local.json (personal, not in git)
5. CLI flags - Command-line arguments
6. Enterprise policies - Organization-level (cannot be overridden)

How Permissions Work

Each scope can define allow, ask, and deny rules:

// ~/.claude/settings.json (user scope - applies everywhere)
{
  "permissions": {
    "allow": ["Read", "Bash(npm test)"],  // Always allowed in any project
    "deny": ["Read(**/.env)"]              // Never allowed anywhere
  }
}

// .claude/settings.json (project scope - only this project)
{
  "permissions": {
    "allow": ["Bash(npm run deploy)"],     // Additional permission for this project
    "deny": ["Read(./secrets/**) "]         // Additional restriction for this project
  }
}

Key points:

• deny rules ALWAYS win, regardless of scope
• Project settings ADD to user settings (don't replace them)
• Use user scope for personal preferences
• Use project scope for team standards

CLAUDE.md Files

Project instructions that Claude reads at the start of every session:

Global instructions:

~/.claude/CLAUDE.md

Applies to all projects. Good for personal coding style preferences.

Project instructions:

./CLAUDE.md

Project-specific standards. Commit to version control for team sharing.

Local project instructions:

./CLAUDE.local.md

Personal project overrides. Add to .gitignore.

See How to Configure CLAUDE.md for detailed guidance.

MCP Server Configuration

Model Context Protocol servers extend Claude's capabilities, but configuration differs significantly between Claude Code and Claude Desktop:

Claude Code MCP Configuration

User-scoped MCP servers (available in all projects):

~/.claude.json

Note: This file is at ~/.claude.json, NOT inside the ~/.claude/ directory. This is a common source of confusion.

Example user-scoped config:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Project-scoped MCP servers (only for current project):

./.mcp.json

Commit this for project-specific MCP servers your team needs.

Important: Claude Code loads MCP servers from BOTH files. Project servers supplement (don't replace) user servers.

Claude Desktop MCP Configuration

Claude Desktop uses a different file:

# macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows
%APPDATA%\Claude\claude_desktop_config.json

# Linux
~/.config/claude-desktop/claude_desktop_config.json

Example Claude Desktop config:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    }
  }
}

Key differences:

• Claude Desktop has NO project-level MCP configuration
• Claude Desktop config is NOT compatible with Claude Code (different file locations)
• You can import Claude Desktop configs into Claude Code with: claude mcp add-from-claude-desktop

See How to Set Up MCP Servers for detailed configuration.

Credentials

macOS: Credentials are stored securely in the system Keychain. Access them via Keychain Access.app under "Claude Code" or "Anthropic".

Linux and Windows:

~/.claude/.credentials.json

This file contains your authentication tokens. Never share or commit this file.

Session History

Claude Code stores conversation history for each project:

~/.claude/projects/{encoded-project-path}/

The project path is URL-encoded (slashes become dashes). For example:

• /Users/sean/myproject becomes -Users-sean-myproject

Each session creates a .jsonl file:

~/.claude/projects/-Users-sean-myproject/
├── session-2025-01-15-09-30-00.jsonl
├── session-2025-01-15-14-22-00.jsonl
└── session-2025-01-16-10-00-00.jsonl

Custom Commands

Create reusable slash commands in markdown files:

Global commands (all projects):

~/.claude/commands/
├── review.md
├── test.md
└── commit.md

Project commands:

.claude/commands/
├── deploy.md
└── setup.md

Invoke with /commandname in Claude Code.

Cache Directory

Analytics and performance cache:

~/.claude/statsig/

Safe to delete if you need to clear cache. Claude Code will recreate it.

Environment Variables

Claude Code respects these environment variables:

Set these in your shell profile (~/.zshrc, ~/.bashrc) or system environment.

Platform-Specific Details

macOS

Default paths:

# Configuration
~/.claude/

# Credentials (Keychain)
# Access via: Keychain Access.app > login > "Claude Code"

# MCP servers
~/.claude.json

# Check actual location
echo $HOME/.claude

Windows (Native)

Default paths:

# Configuration
%USERPROFILE%\.claude\

# Credentials
%USERPROFILE%\.claude\.credentials.json

# MCP servers
%USERPROFILE%\.claude.json

# Check actual location
echo $env:USERPROFILE\.claude

Windows (WSL)

When using Claude Code in WSL, configuration follows Linux conventions:

# Configuration
~/.claude/

# This is separate from Windows native installation
# WSL path: /home/username/.claude/
# Windows path: C:\Users\username\.claude\

Linux

Default paths:

# Configuration
~/.claude/

# Credentials
~/.claude/.credentials.json

# MCP servers
~/.claude.json

# Create directory if missing
mkdir -p ~/.claude

Backup and Migration

Backup Your Configuration

Create a complete backup:

# macOS/Linux
tar -czvf claude-backup.tar.gz \
  ~/.claude/settings.json \
  ~/.claude/settings.local.json \
  ~/.claude/CLAUDE.md \
  ~/.claude/commands/ \
  ~/.claude.json

# Windows PowerShell
Compress-Archive -Path "$env:USERPROFILE\.claude\settings.json", `
  "$env:USERPROFILE\.claude\CLAUDE.md", `
  "$env:USERPROFILE\.claude\commands", `
  "$env:USERPROFILE\.claude.json" `
  -DestinationPath claude-backup.zip

Do not backup:

• .credentials.json - Re-authenticate on new machines
• statsig/ - Cache, will regenerate
• projects/ - Session history, usually not needed

Migrate to a New Machine

1. Copy configuration files:

   # On new machine
   mkdir -p ~/.claude/commands
   
   # Copy from backup
   tar -xzvf claude-backup.tar.gz -C ~/
   

   Copy

2. Re-authenticate:

   claude
   # Follow the browser authentication flow
   

   Copy

3. Verify configuration:

   claude doctor
   

   Copy

Sync Across Machines

For ongoing synchronization, symlink to a synced folder:

# Example using Dropbox
mkdir -p ~/Dropbox/claude-config

# Move and symlink settings
mv ~/.claude/settings.json ~/Dropbox/claude-config/
ln -s ~/Dropbox/claude-config/settings.json ~/.claude/settings.json

# Move and symlink CLAUDE.md
mv ~/.claude/CLAUDE.md ~/Dropbox/claude-config/
ln -s ~/Dropbox/claude-config/CLAUDE.md ~/.claude/CLAUDE.md

Common Confusion Points & Solutions

"Why are my MCP servers not showing up?"

Most common causes:

1. Wrong file location: User MCP config must be at ~/.claude.json (NOT ~/.claude/.claude.json)
2. Using Claude Desktop config with Claude Code: These are separate. Claude Desktop uses claude_desktop_config.json
3. Project MCP not loading: Ensure .mcp.json is in project root, not in .claude/ subdirectory

Debug with:

claude mcp list         # Shows all configured MCP servers
claude mcp get <name>   # Shows specific server config

"Why do permissions work differently in different projects?"

Permissions stack from multiple sources:

1. Check user permissions: cat ~/.claude/settings.json
2. Check project permissions: cat .claude/settings.json
3. Check local overrides: cat .claude/settings.local.json

Remember: deny rules from ANY scope will block an action.

"What's the difference between ~/.claude.json and ~/.claude/settings.json?"

Critical distinction:

• ~/.claude.json - MCP server configuration (outside .claude directory)
• ~/.claude/settings.json - Claude Code behavior settings (inside .claude directory)

These are completely different files with different purposes. Don't confuse them!

Troubleshooting

Configuration Not Loading

1. Verify the file exists and has correct permissions:

   ls -la ~/.claude/
   

   Copy

2. Check file syntax (valid JSON for settings):

   cat ~/.claude/settings.json | python -m json.tool
   

   Copy

3. Run diagnostics:

   claude doctor
   

   Copy

Permission Errors

# Fix permissions on macOS/Linux
chmod 700 ~/.claude
chmod 600 ~/.claude/settings.json
chmod 600 ~/.claude/.credentials.json

Credentials Not Found

If Claude Code cannot find your credentials:

1. Check if credentials file exists (Linux/Windows):

   ls -la ~/.claude/.credentials.json
   

   Copy

2. On macOS, verify Keychain entry:

   • Open Keychain Access
   • Search for "Claude" or "Anthropic"
   • Ensure the entry exists and is not locked

3. Re-authenticate:

   claude logout
   claude
   

   Copy

Reset Configuration

To start fresh:

# Backup first
cp -r ~/.claude ~/.claude.backup

# Remove configuration (preserves credentials on macOS Keychain)
rm -rf ~/.claude/settings.json
rm -rf ~/.claude/settings.local.json
rm -rf ~/.claude/statsig

# Or complete reset (requires re-authentication)
rm -rf ~/.claude

Quick Reference Card

Claude Code File Locations

# User-level (affects all projects)
~/.claude/settings.json           # Behavior settings
~/.claude/CLAUDE.md               # Global instructions
~/.claude.json                    # MCP servers (NOTE: outside .claude/)

# Project-level (current project only)
./.claude/settings.json           # Team settings (commit to git)
./.claude/settings.local.json     # Personal overrides (gitignore)
./CLAUDE.md                       # Project instructions (commit to git)
./CLAUDE.local.md                 # Personal instructions (gitignore)
./.mcp.json                       # Project MCP servers (commit to git)

# System/Enterprise
/etc/claude-code/managed-settings.json    # Linux
/Library/Application Support/ClaudeCode/  # macOS
C:\Program Files\ClaudeCode\             # Windows

Configuration Precedence (lowest to highest)

1. Built-in defaults
2. User config (~/.claude/*)
3. Project config (./.claude/*)
4. Local overrides (*.local.*)
5. CLI flags
6. Enterprise policies (managed)

Permission Resolution

DENY (any scope) → Always blocks
↓
ALLOW (any scope) → Permits if no deny
↓
ASK (default) → Prompts user

Next Steps

• Install Claude Code CLI if you haven't already
• Configure CLAUDE.md for your projects
• Set up MCP servers to extend capabilities
• Manage permissions and sandboxing for security

Need help configuring Claude Code for your team? Inventive HQ helps organizations standardize AI coding tool configurations. Contact us for enterprise setup assistance.