Setting Up MCP in Claude Desktop: The Missing Manual

I found out the hard way last month that Anthropic’s official docs for MCP in Claude Desktop skip over half the stuff you actually need to know to get it working. I spent three hours debugging a stupid trailing comma after I spent another two hours hunting for the config file in the wrong place. Now I’ve set up a half-dozen MCP servers for different projects, so I’m writing this down to save you the headache.

Where to Find (and Edit) Your Config File

First thing: you can’t edit MCP settings from inside the Claude Desktop app. You have to edit the raw JSON config file directly. Where it lives depends on your OS, and it’s not where most people think to look.

macOS

The full path is `~/Library/Application Support/Claude/claude_desktop_config.json`

The problem here is that the `Library` folder is hidden by default in Finder, so you can’t just navigate there by clicking through folders. The easiest way to open it is:

1. Open Finder
2. Click the "Go" menu in the top menu bar
3. Select "Go to Folder"
4. Paste the full path above and hit enter.

If you don’t see the `Claude` folder or the `claude_desktop_config.json` file, that means you’ve never opened Claude Desktop before. Open it once, close it completely, and the file will be created automatically.

One thing I always do before editing: make a copy of the existing config file and save it to your desktop. If you mess something up, you can just copy the original back and start over. I learned that after I once deleted the whole config by accident and had to rebuild my servers from scratch.

Windows

The full path is `%APPDATA%\Claude\claude_desktop_config.json`

To get there fast:

1. Press Win+R to open the Run dialog
2. Paste the path above and hit enter. The folder will open automatically.

Same rule as above: open Claude once first if the folder doesn’t exist.

Minimal Working Config Examples

The config file is just JSON that tells Claude Desktop which MCP servers to launch, what arguments to pass them, and what environment variables they need. The simplest possible valid config is just an empty object, but that doesn’t do anything. Below are two working, runnable configs you can copy and adapt for your own use.

Both examples assume you have Node.js 18 or newer installed on your machine, which is required for most MCP servers you’ll find.

Example 1: Local Filesystem Access (Most Common First Setup)

This config sets up the official Model Context Protocol filesystem server, which lets Claude read and edit files in a specific folder you choose. This is perfect for letting Claude work with your local project files or notes.

```json

{

"mcpServers": {

"my-notes": {

"command": "npx",

"args": [

"-y",

"@modelcontextprotocol/server-filesystem",

"/Users/your-username/Documents/Projects/notes"

]

}

}

}

```

To make this work for you: just replace `/Users/your-username/Documents/Projects/notes` with the actual full path to the folder you want to share with Claude. For Windows, that would look like `C:/Users/your-username/Documents/Notes` (use forward slashes, you don’t need to escape them if you do this).

Example 2: Brave Search MCP (Web Access for Claude)

This example sets up the Brave Search MCP server, which lets Claude do real-time web searches to get up-to-date information. This one requires a free API key from Brave, which you can get from the Brave Search API dashboard.

```json

{

"mcpServers": {

"brave-search": {

"command": "npx",

"args": [

"-y",

"@mcp/brave-search"

],

"env": {

"BRAVE_API_KEY": "your-brave-api-key-goes-here"

}

}

}

}

```

If you want multiple servers running at the same time, just separate them with a comma in the `mcpServers` object. For example, to run both the notes server and the Brave search server, your config would look like this:

```json

{

"mcpServers": {

"my-notes": {

"command": "npx",

"args": [

"-y",

"@modelcontextprotocol/server-filesystem",

"/Users/your-username/Documents/Projects/notes"

]

},

"brave-search": {

"command": "npx",

"args": [

"-y",

"@mcp/brave-search"

],

"env": {

"BRAVE_API_KEY": "your-brave-api-key-goes-here"

}

}

}

}

```

That’s totally valid, you can run as many servers as you want, as long as the JSON is correct.

How to Verify Your Server Is Loaded Correctly

After you save your config, the most important step most people miss: you have to fully restart Claude Desktop. Just closing the window isn’t enough, because Claude keeps running in the background on both macOS and Windows.

To restart properly:

• On macOS: Right-click the Claude icon in your dock, select "Quit", then re-open it from Launchpad.
• On Windows: Click the up arrow in your system tray to see running background apps, right-click the Claude icon, select "Exit", then re-open it from the Start menu.

Once it’s reloaded, here’s how I check if everything is working:

1. Start a new chat (old chats won’t pick up new servers sometimes, for some reason).
2. Look for the small plug icon in the bottom right corner of the input box, next to the send button. Click it.
3. You should see your new server listed, with all of its available functions. For example, the filesystem server will show `read_file`, `list_directory`, etc.

If you want to double-check, just ask Claude directly: "Can you list all connected MCP servers?" If it names your new server, you’re good to go. If it doesn’t, it’s broken, time to debug.

Common Broken Setups (And How to Fix Them)

I’ve debugged pretty much every issue you can run into, here are the most common ones and their fixes:

1. Silent failure: No servers show up at all

9 times out of 10, this is bad JSON. JSON doesn’t allow trailing commas after the last entry in an array or object, unlike JavaScript. One tiny trailing comma will break the entire config, and Claude just silently fails to load any servers, no error message. This is exactly what got me on my first setup, and I wasted three hours before I thought to check it.

Fix: Copy your entire config into a free online JSON validator like jsonlint.com, it’ll point out the exact error in 2 seconds.

2. "Command not found" error in logs

If you check the logs (more on that in a second) and it says `npx: command not found`, this is almost always a PATH issue. If you installed Node.js via a version manager like nvm or fnm, the GUI version of Claude Desktop doesn’t inherit the PATH from your terminal, so it can’t find `npx`.

Fix: Open your terminal and run `which npx` (macOS/Linux) or `where npx` (Windows) to get the full absolute path to npx. Replace the `command` value in your config with that full path. For example, instead of `"command": "npx"`, you’d have `"command": "/Users/john/.nvm/versions/node/v20.11.0/bin/npx"`. That fixes it every time.

3. Wrong file path errors

If you’re on Windows and use backslashes for paths, you have to escape each backslash with another backslash in JSON. So `C:\Users\John\Notes` becomes `C:\\Users\\John\\Notes` in the config. Most of the time, you can just use forward slashes instead, which work fine in JSON on Windows and don’t need escaping, so that’s my go-to trick.

4. Server crashes on launch with permission errors

This usually happens when you try to share a system folder or your entire hard drive with the filesystem server. Claude doesn’t have permission to read all system folders, and even if it did, you don’t want it poking around there anyway.

Fix: Only share specific, non-system folders that you actually want Claude to access. If you still get permission errors, check the folder’s permissions in your OS settings to make sure your user can read it, which it should if it’s your folder.

Where to find logs when you’re stuck

If you can’t figure out what’s wrong, check the logs. They have all the error messages you need:

• macOS: `~/Library/Logs/Claude/`
• Windows: `%APPDATA%\Claude\logs\`

Each server has its own log file named `mcp-server-[your-server-name].log`, so just open the one for your broken server and read the last error. That’s way faster than guessing.

Security Checks Before You Enable Any External MCP Server

MCP servers run as your user on your local machine, which means they have full access to everything you have access to. A malicious MCP server could steal all your files, API keys, or anything else on your machine. I don’t say this to scare you, but it’s important to take a minute to check these things before you add a new server:

First, only share the minimum files and access you need. Don’t point the filesystem server to your entire home folder just because it’s convenient. If you only need Claude to access your project notes, only share that one folder. I once saw someone share their whole `~` folder because they didn’t want to pick a specific folder, that’s a terrible idea. Any compromise would give away all their personal data.

Second, vet the server code before you run it. Any public MCP server on npm should have a public GitHub repo you can check. Spend 30 seconds looking at it: does it have any weird code that phones home to random servers? If it’s a random server someone sent you in a Discord DM or posted on a sketchy site, don’t run it. Stick to servers from well-known maintainers or the official modelcontextprotocol repo.

Third, lock down your config file permissions. Your config file has any API keys you add to MCP servers, so you don’t want other users on your machine to be able to read it. On macOS or Linux, open your terminal and run `chmod 600 "~/Library/Application Support/Claude/claude_desktop_config.json"` to make sure only your user can read it. On Windows, right-click the file, go to Properties > Security, and make sure only your user account has access to it.

Fourth, remove servers you don’t use anymore. I tested three different web search MCP servers before I settled on the Brave one, and I deleted the other two from my config right after. There’s no reason to leave unused servers connected, they just add extra unnecessary attack surface.

Actionable Next Steps

Alright, now you have everything you need to get set up. Here’s what I’d do next:

1. Back up your existing config file to your desktop before you make any changes.
2. Start with one simple server, like the filesystem example above, to get the hang of how it works.
3. After restarting Claude, use the plug icon menu to confirm it’s loaded, then ask Claude to list the files in your shared folder to test it end-to-end.
4. If something breaks, check the logs first, then run your config through a JSON linter if you don’t see an obvious error.
5. Once you have your first server working, add any additional servers one at a time, testing after each add to make debugging easier if something breaks.