How to add an MCP server to Claude Desktop

Quick answer

• The server is in Anthropic's directory: go to Settings > Desktop app, click Manage next to Extensions, then Browse extensions and Install. No JSON and no Node.js install needed.
• You have a command to run locally (such as npx -y @modelcontextprotocol/server-filesystem ...): add it under mcpServers in claude_desktop_config.json, save, then quit Claude Desktop completely and reopen it.
• You have an https URL for a hosted server: add it as a custom connector under Customize > Connectors, + Add, Add custom connector. Don't put it in the config file.

To check what is connected, click the + button at the bottom of the chat box and open Connectors. Each connected server is listed with its tools.

Option 1: desktop extensions

Desktop extensions are local MCP servers packaged as .mcpb files that install like browser extensions. Claude Desktop ships its own Node.js runtime for them, so you don't need Node installed, and fields marked sensitive (such as API keys) are stored in your operating system's keychain.

1. Open Settings > Desktop app and click Manage next to Extensions (in the older settings layout: Settings > Extensions).
2. Click Browse extensions, pick an Anthropic-reviewed extension and click Install.
3. Fill in any settings it asks for, such as an API key or a folder.

To install an .mcpb file someone sent you: on the same page open Advanced settings, find the Extension Developer section and click Install Extension.... Only install files from people you trust. On Team and Enterprise plans an owner can restrict which extensions are allowed.

Option 2: claude_desktop_config.json

For any local server that is not packaged as an extension, list it in the config file. Open it from the Claude menu in your system menu bar (not the settings inside the chat window): Settings..., then the Developer tab, then Edit Config. That creates the file if it doesn't exist. You can also open it directly:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json (or under $XDG_CONFIG_HOME/Claude/ if that is set; this location is from VS Code's documentation, which reads the same file)

This example adds the official Filesystem server with access to two folders. Replace username with your own and keep the paths absolute:

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

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

Then quit Claude Desktop fully (not just close the window) and start it again. Servers in this file need their runtime on your machine. From v2 the official TypeScript reference servers, Filesystem included, need Node.js 24 or newer (what changed).

Adding more servers and API keys

Each server is another entry inside mcpServers. Put keys in an env object. This uses the Brave Search server's package and variable name:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "env": { "BRAVE_API_KEY": "YOUR_API_KEY_HERE" }
    }
  }
}

The key sits in the file as plain text, so keep it private. If the server is also available as a desktop extension, that is the safer way to store a key.

Option 3: remote servers as custom connectors

Hosted servers with an https URL are added to your Claude account rather than to the config file. On Pro and Max: Customize > Connectors, + Add, Add custom connector, enter a name and the server URL, review the detected sign-in settings, and click Add. On Team and Enterprise, an owner adds the connector under Organization settings > Connectors first, then each member clicks Connect. Free plans can have one custom connector.

Two things surprise people. First, Claude connects to a custom connector from Anthropic's cloud, not from your computer, so a server on localhost, a VPN or a private network won't work unless it is reachable from Anthropic's IP ranges. Second, the reverse also holds: servers in claude_desktop_config.json run on your machine and aren't available in Cowork or on claude.ai. Turn connectors on or off per chat from the + button, then Connectors.

Check that it works

1. Click + at the bottom of the chat box and open Connectors. Your server should be listed; open it to see its tools.
2. Ask for something only that server can do, for example "List the files on my Desktop" for the Filesystem server.
3. Claude asks before it runs a tool. Read what it wants to do before you approve, and only choose Allow always for tools you trust.

Connection status and logs for local servers are also on the Extensions page under Local MCP servers (in the older layout, Settings > Developer).

Read the logs

• macOS: ~/Library/Logs/Claude
• Windows: %APPDATA%\Claude\logs
• mcp.log has general connection messages and failures. mcp-server-<name>.log has everything that server printed to stderr, which often includes normal logging, not only errors.

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

type "%APPDATA%\Claude\logs\mcp*.log"

Troubleshooting

• The server doesn't show up: quit and reopen Claude Desktop completely, then check the file is valid JSON (a missing comma or an unescaped Windows backslash breaks the whole file) and that every path is absolute.
• It shows up but fails to connect: run the same command in a terminal, for example npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop, and read the error. Then check mcp-server-<name>.log. A server that starts and exits at once is covered in MCP error -32000 "Connection closed".
• Windows: ENOENT error with ${APPDATA} in the log: the MCP docs suggest adding "APPDATA": "C:\\Users\\<you>\\AppData\\Roaming\\" to the server's env, and making sure npm is installed globally (%APPDATA%\npm should exist; if not, run npm install -g npm). More fixes in Fix "spawn npx ENOENT" on Windows.
• An extension is installed but its tools are missing: restart Claude Desktop, then open the extension's settings and fill in any required fields, such as the API key or folder.
• A remote URL in the config file does nothing: add hosted servers as custom connectors (Option 3) instead.
• Research doesn't use your server: Anthropic notes that advanced Research can't call tools from local MCP servers.

FAQ

Can Claude Code use the servers I set up in Claude Desktop?

Yes. claude mcp add-from-claude-desktop imports them (on macOS and WSL). See the best MCP servers for Claude Code.

Can VS Code use them?

Yes, if you turn on Claude Desktop as a discovery source in the chat.mcp.discovery.enabled setting. See how to add an MCP server to VS Code.

Extension or config file: which should I use?

Use an extension when one exists: it installs with a click, brings its own Node.js and keeps keys in your keychain. Use the config file for servers that aren't packaged as extensions or when you need a specific command or version.