Ask AI:

How to Connect MCP Servers to Claude Desktop

Short answer

Claude Desktop starts local MCP servers from a file called claude_desktop_config.json. On macOS it's ~/Library/Application Support/Claude/claude_desktop_config.json, and on Windows it's %APPDATA%\Claude\claude_desktop_config.json. Put each server under the mcpServers key with the command that starts it, then fully quit and reopen Claude Desktop. Remote servers don't go in that file: you add their URL as a custom connector in the app's Connectors settings.

Tested withMCP spec 2026-07-28Claude Desktop (current release, as documented by Anthropic on 2026-10-20)MCP Inspector 2.11.0@modelcontextprotocol/server-filesystem 2.0.0Checked 20 Oct 2026

By Tony Lewis How we test these guides

What you'll have at the end

Claude Desktop lists your servers and their tools under the Connectors menu, and Claude can call them in a chat. The config below gives you two servers: a filesystem server that can read and write files in folders you choose, and your own bookmarks server from How to build an MCP server.

A local server runs on your machine as a child process of the app. A remote server runs somewhere else, and Anthropic's servers connect to it on Claude's behalf.

Before you start

Claude Desktop installed and signed in. Download it from Anthropic's installation page.
Node.js for the filesystem example. The npx command comes with it.
uv for the bookmarks example, or any other local server you want to add.
For remote servers: a Claude plan that supports custom connectors. Free plans can add one custom connector; Pro, Max, Team and Enterprise plans can add more.

Where the config file lives

Claude Desktop reads the config file when it starts. Use the path for your system:

OS	Config file	How to open it
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`	Claude menu, then Settings..., then Developer, then Edit Config
Windows	`%APPDATA%\Claude\claude_desktop_config.json`	Settings, then Developer, then Edit Config
Linux	`~/.config/Claude/claude_desktop_config.json`	Not in Anthropic's docs. This is the path the community Linux build uses.

Edit Config creates the file if it doesn't exist. %APPDATA% is usually C:\Users\<your name>\AppData\Roaming.

On Linux, quit Claude Desktop before you edit the file. The community build's maintainers note that the app rewrites its own config while it runs, so edits made with the app open can be overwritten.

Add a local server

A local server is a program on your computer that Claude Desktop starts for you. Each entry under mcpServers has a name you choose, the command to run, and the args to pass it.

Open the config file and use the example for your system. It adds the filesystem server from the Model Context Protocol project, which can read and write files in the two folders you list, and a bookmarks server that runs from your own project.

macOS
Windows

claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    },
    "bookmarks": {
      "command": "/Users/username/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/username/projects/bookmarks",
        "run",
        "bookmarks.py"
      ]
    }
  }
}

Replace username with your user name. Replace /Users/username/.local/bin/uv with the output of which uv, and /Users/username/projects/bookmarks with the folder that holds your bookmarks.py.

claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\Desktop",
        "C:\\Users\\username\\Downloads"
      ]
    },
    "bookmarks": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\username\\projects\\bookmarks",
        "run",
        "bookmarks.py"
      ]
    }
  }
}

Replace username with your user name, and point the bookmarks entry at your project folder. Backslashes in JSON strings have to be doubled, as in C:\\Users\\username\\Desktop, or you can use forward slashes.

A few rules matter here:

Use absolute paths. Claude Desktop doesn't start in your project folder, so ./bookmarks.py or ./data won't resolve. Use the full path to the folder or file.
Use the full path for command if the app can't find it. Claude Desktop starts servers with a limited set of environment variables, so your shell's PATH may not apply. Run which npx or which uv on macOS or Linux, or where uv on Windows, and paste the result.
Put the secrets in env, not in args. An env object passes the variables a server needs, such as "MYAPP_API_KEY": "...".

Check the JSON before you restart

A trailing comma or a missing brace stops the file from loading, and none of your servers start. Check the file with python3 -m json.tool claude_desktop_config.json before you restart.

After you save the file, fully quit Claude Desktop and reopen it. Closing the window isn't enough, because the config is read when the app starts. On macOS, press Cmd+Q.

Check that the server connected

Open a new chat and click the plus icon labelled "Add files, connectors, and more". Hover over Connectors, then choose Manage connectors. Your servers appear in the list, and selecting one shows its tools.

If a server is missing, go to Check the logs below.

Add a remote server

A remote server is one you reach over the internet at a https:// URL. You don't add those to the config file. You add the URL as a custom connector.

Open Claude Desktop's settings and select Connectors. Anthropic's help center calls this Customize > Connectors.
Click Add, then Add custom connector.
Enter a name, which is how the connector appears in your list, and the server's URL, such as https://example.com/mcp.
Click Continue. Claude checks the server's authentication settings and suggests a setting.
Choose how you'll sign in under Authentication: Sign in now, Sign in when needed, or No sign in. If the server uses an API key or bearer token instead of OAuth, add it under Request headers.
Click Add.

Remote servers have a catch that catches people out. Claude connects to them from Anthropic's cloud, not from your computer. The URL must be public and reachable from the internet. A server on localhost, on a private network, or behind a VPN won't connect, even if it works from your own browser. For those, use a local server in the config file.

To remove a connector, go back to Connectors, then choose Remove from the connector's menu. To change one, remove it and add it again with the new details.

Most remote servers ask you to sign in through OAuth. When you choose Sign in now or Sign in when needed, Claude opens the server's sign-in page. You sign in there and approve the permissions it asks for. Claude never sees your password.

Read the permission list before you approve it. If a request asks for more access than the tool needs, deny it. You can disconnect the connector in Claude's settings, or revoke access in the service's own security settings.

Claude asks before it runs a tool. Choose Allow always only for tools you trust to run without a prompt. To stop a tool from being offered in a chat, turn it off in the Search and tools menu.

Install a .mcpb extension

A .mcpb file is a packaged local server that Claude Desktop installs as an extension. It bundles the server with a manifest, so you don't edit the config file yourself. What is a .mcpb file? explains the format, and Package an MCP server as .mcpb covers how to make one.

To install one:

Open Settings and select Extensions.
To install a file you have, click Advanced settings, find the Extension Developer section, and click Install Extension.... Select the .mcpb file and follow the prompts.
To install from Anthropic's directory, click Browse extensions and then Install on the one you want.

Extensions from the official directory update automatically. Extensions you install from a file need you to install the new file when it changes.

Check the logs

When a server won't start or a tool fails, the logs show what happened. Claude Desktop writes MCP logs to these folders:

OS	Log folder
macOS	`~/Library/Logs/Claude`
Windows	`%APPDATA%\Claude\logs`
Linux	`~/.config/Claude/logs` (Anthropic documents this folder for the app's main log. Its MCP log names aren't confirmed on Linux.)

Two kinds of file matter. mcp.log covers connections and connection failures for all servers. mcp-server-SERVERNAME.log holds the stderr output of one server, so it shows that server's own errors and logging.

On macOS, follow the logs while you restart the app:

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

On Windows, open them in PowerShell with type "$env:AppData\Claude\logs\mcp*.log". The Windows command only shows recent logs.

Common problems

The server doesn't appear in Connectors. The config file has a syntax error, the app wasn't fully quit, or the path is relative. Run python3 -m json.tool on the file, fully quit and reopen the app, and check mcp.log for the server's name.

An ENOENT error in the logs. The app couldn't find the command or a file it needs. Put the full path to npx or uv in command, and check that every path in args exists.

${APPDATA} appears in a path in the logs (Windows). The server didn't get the expanded APPDATA value. Add it to the server's env object, for example "APPDATA": "C:\\Users\\username\\AppData\\Roaming\\", then restart the app. The MCP docs' local server guide gives this fix.

The server starts, then disconnects straight away. Something is writing to stdout, which corrupts the protocol messages. Use stderr for logging. Fix MCP connection errors covers this and the other causes.

A remote connector shows an error, but the URL works in your browser. Claude connects from Anthropic's cloud, so the server must be public. Check that the URL is https://, that it isn't on localhost or a private network, and that your firewall allows Anthropic's IP addresses if the server is on a private network. Anthropic's custom connector article lists the requirement.

Claude has the tools but doesn't use them. That's a description problem, not a connection problem. Tool names and descriptions covers how to write descriptions the model picks correctly.

FAQ

Where is the Claude Desktop config file on Mac?

It is at ~/Library/Application Support/Claude/claude_desktop_config.json. Open the Claude menu, then Settings, then Developer, and select Edit Config. Edit Config creates the file if it does not exist.

Where is the Claude Desktop config file on Windows?

It is at %APPDATA%\Claude\claude_desktop_config.json. Open Settings, go to Developer, and select Edit Config. Use double backslashes for paths inside the JSON.

Can I add a remote MCP server to the config file?

No. Remote servers are added as custom connectors in the Connectors settings, with their public https:// URL. The config file is for local servers that Claude Desktop starts on your computer.

Why does Claude Desktop not show my MCP server after I edit the config?

Most often the JSON has a syntax error, or the app is still running. Check the file with a JSON validator, fully quit Claude Desktop, and reopen it. Then check mcp.log in the logs folder.

Should I use a .mcpb extension or edit the config file?

Use a .mcpb extension when someone has packaged the server for you, because it installs with no JSON editing. Edit the config file when you run your own server or need to set the command and environment yourself.

Build an MCP serverWrite the bookmarks server used in the config example above.
Fix MCP connection errorsCauses and fixes for servers that won't connect in any app.
Sign in to remote servers with OAuthWhat happens when a server asks you to sign in, and how to revoke access.
Package an MCP server as .mcpbMake a Desktop extension that installs with one click.
Local vs remote MCP serversChoose between a server on your computer and one on the internet.

What you'll have at the end​

Where the config file lives​

Add a local server​

Check that the server connected​

Add a remote server​

Sign in with OAuth​

Install a .mcpb extension​

Check the logs​

Common problems​

FAQ​