Claude Desktop MCP Configuration: The Exact Setup

Claude Desktop MCP configuration is one file: claude_desktop_config.json, holding a single mcpServers object. Get the path right, get the JSON right, then fully quit and reopen — that sequence is the whole job. Everything below is the exact form, plus the four things that actually break it.

Claude Desktop is stdio-only, which shapes every decision here: it launches each server as a local child process and talks to it over standard input/output. That's not a limitation to fight — it's why roughly 90% of MCP servers run locally over stdio in the first place. Remote servers still work, but through a proxy, covered below.

Where claude_desktop_config.json lives

The config file is per-OS, and Claude will not create it for you — if it's missing, make it yourself.

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

The reliable way to open it: Settings → Developer → Edit Config. That opens (or creates) the correct file in your default editor, so you never have to guess the path. If the Developer tab isn't visible, you're on an old build — update first.

The mcpServers shape

Every entry is a named key under mcpServers with a command and its args. Here's a minimal, correct config running the official Filesystem reference server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    }
  }
}

Three things to notice. The key ("filesystem") is just a label you choose. npx -y fetches and runs the package without a global install. The trailing path argument is the directory the server is allowed to touch — Filesystem read/writes only inside the directories you pass, so scope it tight.

Servers that need credentials take an env block. The GitHub MCP Server is the common example:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  }
}

Don't hand-write these from memory. Each server page gives you the exact block, and the config generator merges several servers into one valid file — which matters, because one stray comma invalidates the entire config.

Restart, don't reload

Claude Desktop reads the config once, at launch. Editing the file changes nothing until you fully quit and reopen — on macOS that means Cmd+Q, not closing the window; on Windows, exit from the tray, not the X. This single mistake is behind most "my server isn't showing up" reports. There is no hot reload.

After a proper restart, look for the tools icon in the input box. If your server's tools appear there, configuration succeeded. If not, jump to the four causes below.

Remote servers need the mcp-remote proxy

Claude Desktop has no native remote transport, so a hosted MCP endpoint can't go in as a plain url. You bridge it with the mcp-remote proxy, which runs locally and forwards to the remote server:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://example.com/mcp"]
    }
  }
}

This is why the same server can look different across clients — Cursor might take a url directly while Claude Desktop wraps it. If you're deciding whether to run a server locally or reach for the proxy, local vs remote MCP walks the trade-offs. The Claude client setup page shows the exact bridged form per server.

Don't blow the tool budget

More servers is not better. Every server injects its tools into Claude's active set, and tool selection degrades once you're past roughly 40 tools — that's the practical client budget. A server like Context7, which pulls version-specific library docs into the model, earns its slot; a grab-bag of servers you rarely call just crowds the list and makes Claude pick worse tools.

Be deliberate. Three to five focused servers beats a dozen. Browse the best MCP servers by what you actually do, and cut anything you haven't used in a week.

When it's not working — the four usual causes

Nearly every failed Claude Desktop MCP configuration is one of these:

1. npx not found — Node isn't installed or isn't on Claude's PATH. Install Node; on macOS, launching Claude from Finder can miss a shell-set PATH, so a fresh install to a standard location is safest.
2. Reloaded instead of restarted — see above. Cmd+Q / tray-exit, then reopen.
3. Malformed JSON — a trailing comma or unquoted key breaks the whole file silently. Paste from the server page or the generator instead of editing by hand.
4. Missing env credential — the server needs a token you didn't supply, so it starts and immediately dies. Check the server's auth requirements on its page.

If you're still stuck, the troubleshooting guide has the specific error signatures and fixes. For the full end-to-end walkthrough across clients, see how to add an MCP server.