Hatchloop guides

How to Add an MCP Server to Claude Desktop (Step-by-Step, 2026)

The Model Context Protocol (MCP) lets Claude Desktop talk to local programs that expose tools — file access, search, databases, your own scripts. Adding one is just editing a JSON file and restarting the app. The two things that trip people up are a Windows npx quirk and actually restarting Claude (closing the window isn't enough). This guide covers both.

TL;DR

  1. Open Claude Desktop Settings → Developer → Edit Config. This opens claude_desktop_config.json.
  2. Add your server under mcpServers with a command and args. Use absolute paths.
  3. Windows + npx: wrap it — "command": "cmd", "args": ["/c", "npx", "-y", "<package>"]. Bare npx fails with spawn npx ENOENT.
  4. Fully quit Claude (right-click the tray icon → Quit on Windows, ⌘Q on macOS) and reopen. Closing the window does not reload config.
  5. Confirm the MCP tools indicator appears in the bottom-right of the message box and click it to see the tools.

Validate your JSON first with pip install mcp-config-lint to catch trailing commas and bad paths before you restart.

Prerequisites

Per the official MCP quickstart, you need:

node --version

Most example servers (like the official Filesystem server) are distributed as npm packages and launched with npx, so Node.js is the common dependency. Servers written in Python typically use uv/uvx or python instead.

Step 1 — Open the config via Settings → Developer → Edit Config

  1. Open Claude Desktop.
  2. Go to Settings. On macOS this is in the Claude menu in the system menu bar (not the in-window settings); on Windows it's in the app's Settings.
  3. Select the Developer tab in the left sidebar.
  4. Click Edit Config.

This creates claude_desktop_config.json if it doesn't exist yet, or opens your existing one in your default editor.

Note: "Edit Config" only opens the file in an editor — it does not reload servers. You still have to restart Claude (Step 4).

Step 2 — Know where the config file lives (per OS)

The "Edit Config" button opens the file at these locations:

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

(The official MCP docs cover macOS and Windows; Linux follows the standard ~/.config convention used by community guides.)

⚠️ Windows MSIX caveat: "Edit Config" can open the wrong file

There's a known, documented gotcha. If Claude Desktop was installed as an MSIX package (e.g. via the Microsoft Store or certain enterprise installers), Windows virtualizes the filesystem. The result: "Edit Config" opens the real, non-virtualized path, but the running app reads from the virtualized one — so your servers silently fail to load with no error and no logs at the expected spot. (GitHub issue #26073)

The two paths involved are:

# What "Edit Config" opens
C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json

# What an MSIX-packaged app actually reads
C:\Users\<you>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

If your config looks correct but nothing loads on Windows, check whether you're editing the file the app is actually reading. (Most users on the standard installer won't hit this — but if you're stuck with zero logs, this is the first thing to rule out.)

Step 3 — Add the server JSON

The config is a single JSON object with an mcpServers key. Each entry is a named server with a command, an args array, and an optional env object.

Here's the official Filesystem server example. Replace username with your actual account name and use absolute paths.

macOS / Linux:

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

Windows (note the doubled backslashes in JSON paths):

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

What each field means, per the docs:

Security: the server runs with your user account's permissions, so only grant access to directories you're comfortable letting Claude read and modify.

Adding more than one server is just more keys under mcpServers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop"]
    },
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-server/index.js"]
    }
  }
}

Before you save and restart, validate the JSON. A single trailing comma will break the whole file. The free mcp-config-lint catches malformed JSON, trailing commas, and obviously-relative paths:

pip install mcp-config-lint
mcp-config-lint claude_desktop_config.json

Step 4 (Windows) — Fix the npx gotcha: use cmd /c

This is the single most common Windows failure. If you use a bare "command": "npx" on Windows, the server often fails to spawn with:

spawn npx ENOENT

Why: npx on Windows is a .cmd batch shim, not a native .exe. Node's child_process.spawn (which Claude uses to launch servers) doesn't run shell commands directly on Windows the way it does on macOS/Linux — it expects an executable, so it can't resolve npx and throws ENOENT. (fransiscuss.com writeup)

The fix: wrap the command in cmd /c.

❌ Broken on Windows:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

✅ Working on Windows:

{
  "mcpServers": {
    "context7": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@upstash/context7-mcp@latest"
      ]
    }
  }
}

macOS and Linux do not need this wrapper — bare npx works there.

Related: ENOENT mentioning ${APPDATA} on Windows

A separate but related Windows error: if a server's log shows an error referencing ${APPDATA} in a path, the official docs say to add the expanded value of %APPDATA% to that server's env:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
        "BRAVE_API_KEY": "..."
      }
    }
  }
}

The docs also note npx may keep failing if npm isn't installed globally; if %APPDATA%\npm doesn't exist, run npm install -g npm.

Step 5 — Fully restart Claude Desktop (not just close the window)

Saving the config is not enough — Claude loads MCP servers only at startup. And closing the window does not quit the app; it keeps running in the background, so your changes won't take effect.

If you skip a full restart, nothing will load.

Step 6 — Confirm the tools appear

After a clean restart, look at the bottom-right of the message input box. You'll see an MCP tools indicator (a small slider/tools icon). Click it to see the list of tools your server exposes.

When Claude wants to use one of those tools, it will ask for your approval first — you stay in control of every action.

If the indicator doesn't show up, jump to troubleshooting.

Troubleshooting

From the official MCP troubleshooting guidance, if the server/indicator doesn't appear:

  1. Restart Claude Desktop completely (see Step 5 — the most common miss).
  2. Check your JSON syntax — no trailing commas, balanced braces. Run mcp-config-lint.
  3. Use absolute paths, never relative ones, and make sure they're valid.
  4. Read the logs: - macOS: ~/Library/Logs/Claude - Windows: %APPDATA%\Claude\logs - mcp.log has general connection logging; mcp-server-<NAME>.log has that server's stderr.
  5. Run the server manually in a terminal to surface errors directly, e.g.:
npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads

Windows-specific reminders: apply the cmd /c wrapper (Step 4), and if you're on an MSIX install with no logs at all, verify you're editing the file the app actually reads (Step 2 caveat).

Don't want to fight the config?

If you'd rather skip the JSON, the cmd /c wrapping, and the Windows path archaeology, the Hatchloop MCP Setup Pack ($15) ships ready-to-paste, OS-correct configs for the common servers plus a validation checklist — a shortcut if your time is worth more than the hour of trial and error. Totally optional; everything above works for free.

FAQ

Where is the Claude Desktop config file? macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json. Linux: ~/.config/Claude/claude_desktop_config.json. The fastest way to open it is Settings → Developer → Edit Config.

My MCP server fails with spawn npx ENOENT on Windows. Why? On Windows, npx is a batch shim, not a native executable, and Claude spawns servers without a shell. Wrap the command: set "command": "cmd" and prepend "/c" to the args, e.g. ["/c", "npx", "-y", "<package>"]. macOS/Linux don't need this.

I edited the config but nothing changed. You probably didn't fully restart. Closing the window leaves Claude running. Quit completely — ⌘Q on macOS, or right-click the system-tray icon → Quit on Windows — then reopen.

My Windows config looks perfect but no servers load and there are no logs. You may be on an MSIX install where "Edit Config" opens a different file than the app reads. See the MSIX caveat and check the AppData\Local\Packages\Claude_pzs8sxrjxfjjc\... path.

Do I need Node.js? Only if your server runs via npx/node (most npm-packaged servers do). Python servers use uv/uvx/python instead. Run node --version to check.

How do I add more than one server? Add additional named entries under the same mcpServers object. Each needs its own command and args.

How do I know it worked? After a full restart, an MCP tools indicator appears in the bottom-right of the message box. Click it to view the available tools.

Sources

Published by Hatchloop. Free MCP config linter: pip install mcp-config-lint · MCP Setup Pack → · More guides