claude_desktop_config.json: Location, Format, and How to Edit It

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. 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.

What is claude_desktop_config.json?

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.

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), so if you're in the terminal, that's a separate path. claude_desktop_config.json is specifically the desktop app's control panel for local tools.

Where to find claude_desktop_config.json

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.

How to edit claude_desktop_config.json

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.

claude_desktop_config.json format and example

The file 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"]
    }
  }
}

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

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 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

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.

Security and best practices for claude_desktop_config.json

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 claude_desktop_config.json becomes a small, reliable file you rarely have to think about once your servers are in.