claude_desktop_config.json: Location, Format, and Editing

claude_desktop_config.json is the file where Claude Desktop stores its MCP server configuration. It lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. The easiest way to open it is Claude Desktop → Settings → Developer → Edit Config. It's a JSON file with an mcpServers object; add a server, save, and fully restart Claude Desktop to apply it. The Claude Desktop config JSON file is plain text you can open in any editor.

Config paths, format, and restart behaviour verified 31 July 2026 against Anthropic's guide to local MCP servers on Claude Desktop.

If you're wiring MCP servers into Claude Desktop, claude_desktop_config.json is the one file you'll touch. It tells Claude Desktop which local tools to launch — a filesystem server, a database connector, whatever you're adding — and how to run them. Claude currently spans models like Claude Opus 5 and Claude Sonnet 5, but claude_desktop_config.json works the same whichever one you're chatting with — most edits are a few lines and take under 30 seconds, and this guide is reviewed regularly so the steps stay accurate. Below is exactly where the file lives, how to open it safely, the format with a working example, and the mistakes that keep a server from connecting. Every step below was run by hand before publishing, so you are not testing our assumptions in production.

What is claude_desktop_config.json?

It is Claude Desktop's MCP configuration file. Each entry names one server, the command that launches it, its arguments, and any environment variables. The app reads the file at startup and boots every server listed there.

claude_desktop_config.json is Claude Desktop's configuration file for MCP — the Model Context Protocol that lets Claude connect to external tools. Each entry in the file defines one MCP server: the command to launch it, its arguments, and any environment variables it needs. When Claude Desktop starts, it reads this file and boots every server listed, making their tools available to Claude. In short, the Claude Desktop config JSON file is the single place where those connections are declared.

It's worth being clear on scope: this is the Claude Desktop config. Claude Code manages its MCP servers differently (via claude mcp add and its own config, documented in Anthropic's Claude Code MCP docs), so if you're in the terminal, that's a separate path. The Claude Desktop config JSON is specifically the desktop app's control panel for local tools.

Where to find claude_desktop_config.json

macOS keeps it at ~/Library/Application Support/Claude/claude_desktop_config.json; Windows keeps it at %APPDATA%\Claude\claude_desktop_config.json. If it is missing, that is normal — the app creates it the first time you open it through Developer settings.

The file's location depends on your operating system:

If the file isn't there yet, that's normal — Claude Desktop only creates claude_desktop_config.json once you open it through the app (below) or add one yourself. On Windows, paste %APPDATA%\Claude into File Explorer's address bar to jump straight to the folder. Either path points at the same Claude Desktop config JSON that the app reads on launch.

How to edit claude_desktop_config.json

Use Claude Desktop → Settings → Developer → Edit Config. That opens the file in your default editor and creates it if it does not exist. Save your changes, then fully quit and relaunch the app.

You can open the file directly in a text editor, but the safest way is through the app, which creates the file if it doesn't exist:

1. Open Claude Desktop → Settings.
2. Go to the Developer tab.
3. Click Edit Config.

This opens claude_desktop_config.json in your default editor (creating it on first use). Make your changes, save, then completely quit and restart Claude Desktop — new servers only load on startup, not on save. The same Developer settings screen shows each server's connection status and logs, which is where you check whether an edit actually worked. Editing the Claude Desktop config JSON through the app is safer than hand-creating it, because a typo in the path never leaves you with a half-written file.

Claude Desktop config JSON format and example

The file is one JSON object with a single top-level mcpServers key. Each named server takes a command, an args array, and an optional env block. On Windows, every backslash in a path must be doubled.

The Claude Desktop config JSON is a JSON object with a single top-level key, mcpServers. Each server is a named entry with a command and args. Here's a working filesystem-server example for macOS:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

On Windows, the same server uses escaped backslashes in paths:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\username\\Desktop"]
    }
  }
}

On our own native Windows and PowerShell setup, the escaped-backslash rule is the trap that has cost us the most time, and we mention it because it is so easy to miss. Copy a path straight out of File Explorer into claude_desktop_config.json and every single \ has to be doubled, or the JSON silently refuses to parse and no server loads at all. After getting burned by it once, we started keeping a known-good copy of claude_desktop_config.json next to the live one and running the file through a validator before every restart — thirty seconds that saves a confused round of "why did all my servers vanish." A JSON linter in your editor catches the same mistake before you ever quit the app.

The fields you'll use in claude_desktop_config.json:

To add more servers, add more named entries alongside filesystem inside mcpServers. Keep the JSON valid — a stray comma is the most common reason the whole file fails to load.

Troubleshooting claude_desktop_config.json

Five causes cover nearly every failure: you did not fully restart, the JSON is invalid, you edited a copy at the wrong path, the command is not on your PATH, or the server itself errored — read the Developer logs.

If a server doesn't show up in Claude Desktop, work through these:

1. You didn't restart. Servers load on startup — fully quit Claude Desktop (not just close the window) and reopen it.
2. The JSON is invalid. A trailing comma, missing bracket, or unescaped Windows backslash breaks the file. Paste it into a JSON validator to check.
3. Wrong file location. Confirm you edited claude_desktop_config.json at the exact path for your OS, not a copy somewhere else.
4. The command isn't found. If command is npx or uvx, make sure Node.js or uv is installed and on your PATH.
5. Check the logs. The Developer settings screen shows per-server status and errors — the fastest way to see why a server failed.

Almost every broken config is one of those five. Once the server connects, its tools appear in Claude Desktop automatically. If a bad edit goes further than a missing server and leaves the app hanging on startup or showing a blank window, our guide to the Claude desktop app not working walks through isolating the config from the app itself. If you also use the terminal agent, our Claude Code MCP guide covers the CLI equivalent, and Claude Code Desktop explains the desktop coding app.

Adding your first server to claude_desktop_config.json

Open the config through Developer settings, paste a server block under mcpServers, save, fully quit, relaunch, then confirm the server shows as connected. Testing it with a real request is the final step.

The format alone doesn't show the flow, so let's add a real server end to end. Say you want Claude Desktop to read local files:

1. Open the config via Settings → Developer → Edit Config.
2. Paste a server entry under mcpServers — the filesystem example above, pointing at folders you want Claude to access.
3. Save the file and fully quit Claude Desktop.
4. Reopen it and check Developer settings; the filesystem server should show as connected.
5. Test it by asking Claude to list the files in one of the folders you granted.

That five-step loop is the whole workflow for anything you add to claude_desktop_config.json — only the server entry changes. Anthropic's getting started with local MCP servers guide walks the same path with screenshots, and the official Model Context Protocol docs list many ready-made servers you can drop in.

Popular first additions: a filesystem server for local files, a database server (Postgres or SQLite) for querying data, a GitHub server for repos, and a fetch server for the web. Each is just another named block inside mcpServers with its own command and args — usually an npx or uvx one-liner you copy from the server's README. Because they all share the same shape, once you've added one server to claude_desktop_config.json, adding ten more is mechanical. Every addition is just another block inside the same Claude Desktop config JSON. For a fuller walkthrough of wiring up servers, see our guide to adding MCP to Claude Code.

Security and best practices for claude_desktop_config.json

Scope filesystem servers to specific folders rather than your home directory, keep API keys in each server's env block instead of chat, install only servers you trust, back up a working file, and validate the JSON before restarting.

claude_desktop_config.json grants real capabilities to Claude, so treat it like any other place you configure system access:

• Scope the filesystem server. It only reaches the folders you list in args. Point it at the directories Claude actually needs, not your whole home folder, so a mistaken action can't touch everything.
• Keep secrets in env, not in prompts. When a server needs an API key, put it in that server's env block rather than pasting it into chat — the config isn't sent to the model as message content.
• Only add servers you trust. Each MCP server runs a command on your machine with your permissions. Install from reputable sources and read what a server does before adding it to claude_desktop_config.json.
• Back up a working config. Before a big change, copy the file. If a bad edit stops Claude Desktop from loading any servers, you can restore the known-good version in seconds.
• Validate before you restart. Run the JSON through a validator so a stray comma doesn't cost you a confused restart cycle.

None of this is heavy — it's the same care you'd take with any config that launches local tools. Get the scoping and secrets right, keep the JSON valid, and the Claude Desktop config JSON becomes a small, reliable file you rarely have to think about once your servers are in.