claude_desktop_config.json: The Complete Guide

Every MCP server you use with Claude Desktop is defined in one place: claude_desktop_config.json. Get this file right and your servers just work. Get it wrong — a trailing comma, a missing bracket, a backslash where there should be a forward slash — and nothing loads with no obvious error. This guide covers the full file format, where to find it on every platform, and every mistake worth avoiding.

What the File Does

claude_desktop_config.json is the configuration file Claude Desktop reads at startup to determine which MCP servers to connect to. For each server listed, Claude Desktop spawns a subprocess (for local servers) or prepares an HTTP connection (for remote servers), runs the MCP initialization handshake, and makes the server's tools available in your conversation.

The file doesn't exist until you create it. Installing Claude Desktop doesn't create this file automatically — you create it yourself the first time you add a server. If the file is missing, Claude Desktop simply starts with no MCP servers loaded.

Where the File Lives

macOS

On macOS, the file is at:

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

The Library folder is hidden by default in Finder. The fastest way to get there: open Finder, press Cmd+Shift+G, and paste the path above.

Windows

On Windows, the file is at:

%APPDATA%\Claude\claude_desktop_config.json

Press Win+R, type %APPDATA%\Claude, and press Enter to open the folder directly. If the Claude folder doesn't exist yet, create it manually.

Linux

On Linux (if using a Claude Desktop build), the file follows the XDG convention:

~/.config/Claude/claude_desktop_config.json

The Full File Structure

The file is a standard JSON object with one top-level key: mcpServers. Its value is a dictionary where each key is your chosen name for the server, and the value is a configuration object for that server.

Here is a complete, working example with three servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key_here"
      }
    }
  }
}

The mcpServers Key

Every server entry inside mcpServers is identified by a string key — the server name. This name is arbitrary; it's what Claude Desktop uses internally to label the server. You'll see it in logs and error messages. Keep names short and descriptive: "filesystem", "github", "postgres" rather than "my-awesome-server-v2".

You can have as many servers as you want in mcpServers. They all load in parallel when Claude Desktop starts.

Config Object Fields

command

The command field is the executable that Claude Desktop runs to start the server process. This must be a command available in your system PATH, or an absolute path to the executable. Common values:

• "npx" — runs an npm package without installing it globally (most common for MCP servers distributed as npm packages)
• "node" — runs a local Node.js script
• "python" or "python3" — runs a Python-based server
• "uvx" — the uv equivalent of npx, for Python packages

args

The args field is a JSON array of strings passed as command-line arguments to the executable. When using npx, the typical pattern is:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allow"]

The -y flag is important: without it, npx will prompt for confirmation when installing the package, which blocks the server from starting since there's no terminal to respond to the prompt.

env

The env field is an optional object of environment variables to inject into the server process's environment. Use it for API keys and secrets. These values are not sent to Claude — they're only available to the server subprocess.

"env": {
  "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx",
  "LOG_LEVEL": "info"
}

All values in env must be strings. If you need to pass a number, wrap it in quotes: "MAX_RESULTS": "50".

Common Mistakes That Break Everything

Trailing Commas

JSON does not allow trailing commas. This is valid JSON:

{"args": ["-y", "@modelcontextprotocol/server-github"]}

This is not valid JSON and will silently break your entire config:

{"args": ["-y", "@modelcontextprotocol/server-github",]}

Wrong Path Separators on Windows

Inside a JSON string, a backslash is an escape character. A single backslash will cause a parse error or unexpected behavior. When writing Windows paths in JSON, use one of these approaches:

// Option 1: forward slashes (recommended)
"C:/Users/yourname/Documents"

// Option 2: escaped backslashes
"C:\\Users\\yourname\\Documents"

Not Restarting Claude Desktop

Claude Desktop reads the config file once at startup. Editing the file while Claude Desktop is running has no effect until you fully quit (use File > Quit or Cmd+Q / Alt+F4, not just close the window) and relaunch.

Wrong Indentation or Mismatched Braces

Every opening { needs a closing }, and every [ needs a ]. Editors like VS Code highlight mismatches in real time and will underline JSON errors.

Validating Your JSON Before Restarting

Before restarting Claude Desktop, validate your config with one of these methods:

• VS Code: Open the file in VS Code. It automatically highlights JSON syntax errors with red underlines. Hover the error for details.
• jsonlint.com: Paste the entire file contents. It reports the exact line and character of any syntax error.
• Terminal: On macOS/Linux, run python3 -m json.tool claude_desktop_config.json — it prints the parsed JSON or an error with the line number.

What Happens at Startup

When Claude Desktop launches, it reads claude_desktop_config.json and for each entry in mcpServers:

1. Spawns the process using command and args, with env variables injected.
2. Establishes a stdio pipe to communicate with the process.
3. Sends an initialize request to start the MCP handshake.
4. Receives the server's capabilities (tools, resources, prompts it offers).
5. Makes those capabilities available in your Claude conversations.

If any step fails — the command isn't found, the process crashes on startup, the handshake fails — that server simply won't appear. The others still load normally.

Troubleshooting: Server Doesn't Appear

If a server you added doesn't show up after restarting Claude Desktop, work through this checklist:

1. Validate the JSON. Paste your config into a JSON validator. A single syntax error means the entire file fails to parse and no servers load.
2. Check that the command is in PATH. Open a terminal and run the command manually — e.g., npx --version. If it's not found, Claude Desktop can't find it either.
3. Check the MCP logs. In Claude Desktop, go to Settings and look for a Logs or Developer section. The MCP log shows the exact error when a server fails to start.
4. Verify any required environment variables. If the server needs an API key and env is missing or has a typo in the key name, the server will start but immediately exit.
5. Try running the command manually in a terminal. For example: npx -y @modelcontextprotocol/server-github. If it fails or throws an error, you'll see the reason directly.