How to Connect an MCP Server to Claude Desktop

Contents

Figure 1: How to Connect an MCP Server to Claude Desktop — pick the right route before you touch the config

You have built an MCP server, or found one you want to try, and now you need Claude Desktop to talk to it. This is where most people hit their first wall: a missing restart, a relative path, or a config file in the wrong place.

The good news is that Claude Desktop gives you three clear routes, and picking the right one for your server solves most problems before they start. This guide walks through each route, with a full example for a local server and a troubleshooting checklist.

Caveat on this one: I researched it in October 2026, and numbered brackets like [1] point to the sources at the end. Claude Desktop's menus and features change between releases, so confirm each step against the current Anthropic help article. I could not open that article directly, so some details below come from secondary guides, and I flag those where they appear.

Pick the Right Route

One guide describes the central trap well: Claude Desktop has three separate places where you can configure a server, and almost every "my MCP server won't load" problem comes from using the wrong one for your kind of server [3]. Match your server to its route:

Your server	Route	Where
A packaged extension (.mcpb) or one in the extension directory	Install it	Settings → Extensions [3][4]
A remote server with an HTTPS URL	Custom connector	Settings → Connectors → Add custom connector [1][3]
A local server you run yourself	Config file	Settings → Developer → Edit Config [1][3]

A third-party guide also says that Anthropic's current local MCP help article recommends desktop extensions as the streamlined path for local servers, and that local extensions and config-based local servers work in Claude Desktop only, not in the web app [5]. Check Anthropic's help center for the latest.

Route 1: Desktop Extensions (Easiest for Local Servers)

A desktop extension bundles a local MCP server and its manifest into a single .mcpb file that installs like a browser extension [4]. Older guides call these .dxt files, which is the legacy name [5].

Here is the flow described across guides:

1. Open Claude Desktop and go to Settings, then Extensions.
2. Click Browse extensions to install from the curated directory, or open a .mcpb file you downloaded and click Install [1][4].
3. For unlisted bundles, one guide says to look under the advanced settings for an option to install an extension from a file [4].

Extensions install with one click and update themselves, according to one guide [1]. Use this route when someone hands you a .mcpb file, or when the server appears in the directory.

Route 2: Custom Connectors (Remote Servers)

For a server that offers a URL, the setup is short:

1. Open Settings, go to Connectors, and choose Add custom connector.
2. Paste the server URL.
3. Approve the sign-in when your browser opens [1][5].

The connector then shows as connected, and its tools become available in new chats [5].

A third-party guide adds that custom connectors using remote MCP are available on Claude, Cowork and Claude Desktop [5]. Availability can depend on your plan, so check the help center before you plan around it.

Route 3: The Config File (Local Servers You Run Yourself)

This route gives you full control, and it is the one you will use for the SQLite and Postgres servers from my earlier tutorial. Claude Desktop reads a JSON file that tells it which servers to start and how.

Step 1: Open the Config File

The easiest way: open Claude Desktop, go to Settings, choose the Developer tab, and click Edit Config [1][2]. On macOS, one guide notes that you should use the menu bar's Settings entry, not the in-window settings [4].

The file lives here by default [2]:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

A Windows gotcha: two guides report that Microsoft Store, WinGet and MSIX installs read the config from a different, virtualized path under %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\, even though Edit Config may open the non-virtualized file [3][4]. If your edits seem to do nothing on Windows, check which install type you have.

Step 2: Add Your Server

The official MCP documentation uses the Filesystem server as its example. It tells Claude Desktop to start the server with access to specific directories [2]:

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

The name "filesystem" is a friendly label that appears in Claude Desktop, and the package name tells npx what to run [2]. The MCP docs note that the Filesystem server and many other servers require Node.js [2].

For your own Python server, such as the SQLite one from my previous tutorial, the config looks like this:

{
  "mcpServers": {
    "sqlite": {
      "command": "/absolute/path/to/python",
      "args": ["/absolute/path/to/sqlite_mcp.py"],
      "env": {"SQLITE_DB_PATH": "/absolute/path/to/app.db"}
    }
  }
}

Use absolute paths everywhere. One guide says Claude Desktop prefers them inside the config file [5]. From my own experience of how desktop apps launch processes, they often start with a smaller PATH than your terminal, so a full path to your Python interpreter avoids "command not found" errors. I did not verify that point against Anthropic's docs, so test it on your machine.

Step 3: Save and Fully Restart

Save the file, then quit Claude Desktop completely and reopen it. Closing the window is not enough. One guide says to quit from the menu bar icon on macOS or the system tray on Windows, and it calls the missed restart the single most common reason local setups "don't work" [5].

Step 4: Confirm It Works

After the restart, check these places:

• Developer settings: one guide says a successful local server shows up with a running tag, along with the command and arguments it launched with [5].
• The chat interface: the MCP docs show indicators in the chat window that list available tools [2]. Another guide says connected tools appear in the connectors picker [5].
• A test prompt: ask Claude something that needs the tool, like "list the tables in my database." Claude may ask for permission the first time it uses a new tool [5].

Troubleshooting Checklist

When a server does not show up, work through this list in order:

1. Check JSON syntax. A stray comma breaks the whole file. The MCP docs list syntax checking as a first troubleshooting step [2]. Paste your config into a JSON validator.
2. Check every path. Make sure each file path in the config exists, and that it is absolute [2][5].
3. Check your runtime. Confirm Node.js for npx servers, or Python and your packages for Python servers [2].
4. Run the command by hand. Copy the command and args into a terminal and see whether the server starts. The MCP docs show running the Filesystem server manually this way [2].
5. Restart fully. Quit from the menu bar or tray, not only the window [5].
6. Check the logs. Claude Desktop writes a general connection log and one log per server [1]. One guide says server logs use names like mcp-server-SERVERNAME.log and points you to Developer settings to find them [5]. Another says macOS logs live under ~/Library/Logs/Claude/ [5]. Look for errors there first.
7. Check the Windows install type if edits seem ignored [3][4].
8. Confirm you used the right route. A remote URL belongs in connectors, and a local script belongs in the config file or an extension [3].

Safety Before You Connect Anything

A local MCP server runs on your machine with your user permissions, so treat installation like running any program:

• Install only servers you trust, and read their source or documentation first.
• Limit what each server can touch. The Filesystem example takes an explicit list of directories, so give it only the folders it needs [2].
• Prefer read-only database credentials for any database server, as my tutorial shows.
• Remember that secrets in the config file sit in plain text on your disk. Use restricted accounts and tokens you can revoke.
• Watch tool permission prompts, and decline anything you did not expect.
• Be careful with untrusted content. Text from documents, web pages or databases can try to steer the model. Keep tool access narrow.

A Few Extras

• Claude Code users: one guide says you can import servers you set up in the desktop app with claude mcp add-from-claude-desktop on macOS and Windows Subsystem for Linux [1]. Check Anthropic's Claude Code docs for the current syntax.
• Shared names: the same guide says that when a server name exists in both the desktop file and other config files, the Code tab takes the desktop file's definition [1].
• Docker: one guide mentions that Docker Desktop includes an MCP toolkit that can manage containerised servers and connect them to Claude Desktop [4]. Check Docker's docs for details.

Common Pitfalls

1. Using the wrong route. Remote URLs do not go in the config file.
2. Skipping the full restart. Closing the window does not reload the config.
3. Using relative paths. Absolute paths avoid most launch problems.
4. Editing the wrong file on Windows. Store installs can read a different location.
5. Ignoring the logs. The answer usually sits in the server's log file.
6. Granting broad access. Start narrow, and widen only when needed.

Your Quick-Start Checklist

1. Decide your route: extension, custom connector, or config file.
2. For the config file, open Settings → Developer → Edit Config.
3. Add your server with absolute paths and any environment variables.
4. Validate the JSON.
5. Quit Claude Desktop fully, and reopen it.
6. Confirm the server in Developer settings and with a test prompt.
7. Check logs if something fails.
8. Limit permissions, and trust only servers you have reviewed.

One Subscription Instead of Five AI Tools

The server and the setup above are free; the only paid part is the assistant you connect them to.

Wrapping Up

Connecting an MCP server to Claude Desktop comes down to choosing the right route and avoiding three classic mistakes: bad JSON, relative paths and a missed restart. Extensions handle packaged servers, custom connectors handle remote ones, and the config file handles everything you run yourself.

Start with the Filesystem example from the MCP docs to prove your setup works, then swap in your own server. When something breaks, read the log before you change anything else.

If the server side is still the open question, the transports comparison explains why a local server starts as a subprocess, and MCP server development in Python covers writing one that behaves well under this config.

Frequently Asked Questions

Why doesn't my MCP server show up in Claude Desktop?

Work down four checks in order. First, is the JSON valid, because one stray comma silently breaks the whole file. Second, are all paths absolute and correct, since desktop apps often launch processes with a smaller PATH than your terminal. Third, did you fully quit and reopen the app rather than close the window. Fourth, on Windows, did you edit the file the app actually reads, because Store, WinGet and MSIX installs can use a virtualized path under %LOCALAPPDATA%. If all four pass, read the server's own log.

Where is claude_desktop_config.json?

On macOS it is normally at ~/Library/Application Support/Claude/claude_desktop_config.json, and on Windows at %APPDATA%\Claude\claude_desktop_config.json. The reliable way to reach it is Settings, then Developer, then Edit Config. On Windows, though, Microsoft Store, WinGet and MSIX installs can read a different, virtualized copy under %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude, so check your install type if your edits appear to do nothing.

Do I need to restart Claude Desktop after editing the config?

Yes, and closing the window is not a restart. Quit from the menu bar icon on macOS or from the system tray on Windows, then reopen the app. One guide calls the missed restart the single most common reason local setups appear not to work, and it is the cheapest thing to rule out. Reloading the window does not re-read the config file.

Can I use a local MCP server in the Claude web app?

No. A local server defined in claude_desktop_config.json, or installed as a local extension, runs on your machine and is only available in Claude Desktop, not in the web app. Remote servers are the portable case: those go in as custom connectors and can be available across the products, subject to your plan. Check the help center before you plan around availability.

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

Use an extension when someone hands you a .mcpb bundle or the server is listed in the directory, because it installs in a click and updates itself. Use the config file for servers you run yourself and want full control over, such as a Python script with environment variables. The config-file route is also the one that makes each launch explicit, which is easier to debug when something fails.

Is it safe to install a local MCP server?

A local server runs on your machine with your user permissions, so treat it like any program you install. Read the source or the documentation first, give it the narrowest access it needs, prefer read-only database credentials, and keep secrets in revocable tokens because config values sit in plain text on disk. Watch the permission prompts and decline anything you did not expect.

Sources

• [1] Host Tracker, "How to connect MCP servers to Claude Desktop" — routes, config paths, extensions, logs, Claude Code import, the custom connector flow and the full restart step: host-tracker.com
• [2] Model Context Protocol documentation, "Connect to local MCP servers" — Filesystem server example, config paths, troubleshooting: modelcontextprotocol.io/docs/develop
• [3] Mesa, "Configure MCP servers in Claude Desktop" — the three configuration places and the Windows virtualized path: getmesa.com
• [4] Desktop extension guides — .mcpb bundles, the legacy .dxt name, installing from file, Docker Desktop's MCP toolkit, and the Windows Store virtualized config path; cited by description, no stable URL captured.
• [5] Secondary setup and log guides — Anthropic's local MCP help summary, Developer settings' running tag, absolute-path preference, first-use permission prompts, per-server logs such as mcp-server-SERVERNAME.log, and macOS logs under ~/Library/Logs/Claude/; cited by description, no stable URL captured.

Related Articles

• Build an MCP Server for Your Database (SQLite and Postgres)
• MCP Transports Explained: stdio vs HTTP
• MCP Server Development in Python: First Tool to Production
• MCP vs Function Calling: Difference and When to Use Each