Claude Code and Claude Desktop MCP config file: location and format (Windows/Mac/Linux)

TL;DR: Find Claude Desktop's claude_desktop_config.json in the OS paths below, while Claude Code CLI stores local/user servers in ~/.claude.json and shared project servers in .mcp.json.

Checked 27 October 2026. Check which client is running before you edit a file. Desktop Chat, the Desktop Code tab and the standalone CLI can load different server definitions, so match the entry to the file that client reads.

Where is the Claude Desktop MCP config file?

The official local-server guide lists these Desktop paths. It also describes Settings, Developer, Edit Config, which creates the file if needed. These entries configure locally launched servers.

Platform	Desktop Chat config location	Qualification
Windows	%APPDATA%\Claude\claude_desktop_config.json	Documented default; check the MSIX exception below.
macOS	~/Library/Application Support/Claude/claude_desktop_config.json	Use Finder's Go to Folder for the hidden Library.
Linux beta	Confirm the file opened by Developer, Edit Config.	The vendor Linux installation page does not specify a config-file path.

On Windows, paste %APPDATA%\Claude into File Explorer's address bar. It normally resolves under C:\Users\<you>\AppData\Roaming. Keep a copy of the existing JSON before merging a new server entry; do not overwrite unrelated preferences.

For packaged Windows installs, issue #26073 reports a second file under this directory:

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

This MSIX path comes from user reports and may not apply to your installation. If Edit Config changes have no effect, compare both files and the app's diagnostics before making another edit. The thread includes reports where editing the packaged copy still did not resolve the failure.

Anthropic documents an official Desktop beta for Ubuntu and Debian. For the official beta, confirm the path in the installed app; a community build's ~/.config/Claude/ convention may not identify its active file.

What does the mcpServers JSON format look like?

A Desktop local server is an entry inside mcpServers, with an executable in command and separate strings in args. This Windows example follows the filesystem-server pattern from the official guide:

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

Create the example folder or replace it with the intended directory. The filesystem server can modify files there, so choose a limited test folder. Keep a second server as a sibling entry inside the same object rather than adding another top-level mcpServers key.

JSON writes the path as "C:\\mcp-demo"; the parsed value contains single backslashes. Do not copy Markdown escaping into the file a second time. Comments and trailing commas are invalid JSON. Parse locally rather than uploading a file containing credentials to an online validator.

Remote Desktop services use custom connectors, with account-managed authentication. Do not assume replacing command with url in the local Desktop file creates a remote connector. Those account connectors originate from Anthropic's infrastructure, so a localhost URL is a different networking problem.

Where is the Claude Code MCP config file?

Claude Code's MCP scopes distinguish private project configuration from shared project configuration:

Scope	Stored in	Applies to
Local, the default	~/.claude.json, under the project path	You in this project.
User	~/.claude.json	You across projects.
Project	.mcp.json at the project root	A shared project definition.

On Windows, the default home file is %USERPROFILE%\.claude.json. On macOS and Linux, it is ~/.claude.json. The settings reference distinguishes this state file from ~/.claude/settings.json, which holds preferences and permission settings. Use the CLI to register a server instead of replacing a state file that also contains account and project data.

The Desktop Code-tab documentation adds a qualification: local Code sessions also load Desktop Chat's config. For a same-name conflict there, the Desktop file wins. The standalone CLI does not read that Desktop file. Identify the surface before diagnosing a duplicate server.

How do you add MCP servers without editing JSON directly?

Specify scope explicitly. For an installed local server, substitute its real executable and script paths in this command shape; text after -- belongs to the server:

claude mcp add --transport stdio --scope user myserver -- node /absolute/path/server.mjs
claude mcp add --transport http --scope project docs https://mcp.example.com/mcp
claude mcp list
claude mcp get myserver

The URL is a placeholder, not a working service. For a temporary config, the CLI reference documents --mcp-config; add --strict-mcp-config to isolate the supplied servers from other MCP configurations. This is useful when testing which definition is being loaded.

claude --strict-mcp-config --mcp-config ./test-servers.json

Project files can use ${VAR} and ${VAR:-default} expansion. Supply a server-specific variable through the launching environment and keep real credentials out of version control. Do not assume an env value on one same-name server is merged into another scope's definition. For command parsing problems, use the claude mcp add errors guide.

What Windows-specific issues cause MCP servers to fail?

Check the parsed path and executable resolution before reinstalling packages. A command working in an interactive terminal does not establish that a GUI process inherits the same environment. Use absolute executable/script paths when the launcher cannot resolve them.

Windows batch launchers need special handling: Node's child-process documentation explains that .cmd and .bat files need a shell rather than direct execFile execution. Whether a host supplies that wrapper matters; globally reinstalling npm is not a universal repair. The Windows spawn ENOENT guide separates launch failures from connection failures.

A Windows-native process and a process inside WSL have different home directories and executable paths. Check the environment running the client before selecting the file. Avoid copying a Windows command path into a Linux configuration simply because both clients use the same filename.

How do you verify the active MCP configuration?

1. Back up the file and validate its JSON before changing another setting.
2. For Desktop, fully quit and reopen the app, then inspect the server's available tools.
3. For the CLI, run claude mcp list and inspect the named entry with claude mcp get.
4. In an interactive Code session, review project-server approval and connection status in /mcp, then try one harmless tool call.

Desktop's documented logs are ~/Library/Logs/Claude/mcp*.log on macOS and %APPDATA%\Claude\logs\ on Windows. Read the error before changing transports. Finish by calling a harmless tool; a listed entry alone does not prove the connection works.

FAQ

Where is the Claude Desktop config file on Windows?

The documented default is %APPDATA%\Claude\claude_desktop_config.json. Packaged installs can have a second copy under LocalCache, as reported in issue #26073; confirm which file the running app uses.

Why are my Claude Code MCP servers not loading?

Check the client, scope, JSON, executable path and approval state. A preferences file is not the server registry, and a valid entry does not prove the server connected.

What is the difference between user scope and project scope?

User scope is private across projects; project scope shares a definition in .mcp.json. Local scope is also private, but only for the current project, and is the CLI default.

Can I add MCP servers without editing JSON manually?

Yes, use claude mcp add with an explicit scope. Use --mcp-config for a session file and --strict-mcp-config when that file should be the only MCP source.

Can I share MCP server configuration with my team?

Commit a reviewed .mcp.json without real secrets, and have each person provide their required environment values. Interactive Claude Code sessions prompt for project-server approval.

Does Claude Desktop work on Linux?

Yes, Anthropic documents an official beta for Ubuntu and Debian. Confirm the config path from the installed app rather than assuming an old community build's directory is authoritative.