How to add an MCP server to Claude Desktop

Where Claude Desktop keeps its MCP config

macOS

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

Windows

%APPDATA%\Claude\claude_desktop_config.json

Open the config file

You do not have to find the file by hand. In Claude Desktop, open Settings, go to the Developer tab and choose Edit Config — it opens the right file in your editor and creates it if it does not exist yet.

If you would rather open it directly, it lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

Add the server

Every entry goes under the mcpServers key, keyed by whatever name you want to see in the client. The command is what Claude runs; args is the argument list passed to it.

If the file was empty, paste the whole block. If you already have servers, add your new one as another key inside the existing mcpServers object rather than a second mcpServers block.

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

Pass credentials with env, not args

Servers that reach a paid or private API need a token. Put it in an env object on the server entry — arguments can end up in process listings and shell history, environment variables are the convention every MCP server expects.

Scope the token to the narrowest thing that works. A read-only key that covers your use case is a materially smaller problem than a full-access key if the server turns out to do more than you expected.

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

Verify it worked

Restart the client completely — not just the window. Most MCP clients read their config once at startup, so a reload leaves the old server list in place and makes a correct config look broken.

Then ask the assistant what tools it has. A server that connected will list its tools by name; a server that failed usually says nothing at all, which is the tell.

If the server does not appear

Check the JSON parses. A trailing comma is the single most common cause of a server that silently never appears — the client cannot read the file, so it falls back to no servers rather than reporting an error.

Use an absolute path to the command. Clients do not always launch with your shell's PATH, so `npx` may resolve interactively and fail on startup. `which npx` gives you the full path to paste in.

Check the server actually runs on its own. Paste the same command into a terminal: if it exits immediately, the problem is the server or its credentials, not the client config.

Frequently asked questions

Where is claude_desktop_config.json?

On macOS it is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it is at %APPDATA%\Claude\claude_desktop_config.json. The fastest way to open it is Settings, Developer, Edit Config.

Do I have to restart Claude Desktop?

Yes. The config is read once at startup, so quit the application completely and reopen it. Closing the window is not enough on macOS — use Quit.

Why does my server not show up?

Almost always invalid JSON or a command the client cannot find. Check for a trailing comma, then replace the bare command with its absolute path, since desktop apps do not inherit your shell PATH.