Claude Desktop MCP Setup

Overview

Claude Desktop can connect to local MCP (Model Context Protocol) servers, which are programs that run on your computer and expose tools Claude can call with your approval — reading files, querying a database, searching the web, and more. You enable these servers by editing a single JSON file, claude_desktop_config.json, that tells Claude Desktop which servers to launch and how to run them.

This guide walks through the official setup flow using the Filesystem Server as the worked example: where the config file lives, the exact mcpServers JSON structure, how to start and verify a server, and how to read the logs when something fails. The same pattern applies to any stdio MCP server.

A few facts worth knowing up front:

• Claude Desktop is available for macOS and Windows.
• Many servers (including the Filesystem Server) need Node.js installed, because they are launched with npx.
• Every tool action a server takes requires your explicit approval before it runs, so you stay in control of file and system access.

Prerequisites

• Claude Desktop installed (macOS or Windows). To confirm you are on the latest build, open the Claude menu and choose "Check for Updates...".
• Node.js installed, required for the Filesystem Server and most stdio servers. Verify with:

node --version

If it is missing, install the LTS release from nodejs.org. If npx fails on Windows, confirm npm is installed globally (%APPDATA%\npm should exist).

Config file location

The configuration is the same file regardless of how many servers you add. Its path differs by operating system:

You do not need to find this file by hand. The fastest way to open it is from inside the app, described in the next section, which creates the file if it does not yet exist.

Step-by-step setup

1. Open Claude Desktop settings. Click the Claude menu in your system menu bar (not the gear inside the Claude window) and choose Settings.... This opens the desktop configuration window, which is separate from your Claude account settings.
2. Open the config file. In the Settings window, select the Developer tab in the left sidebar, then click Edit Config. This creates claude_desktop_config.json if it does not exist and opens it for editing.
3. Add a server. Replace the file contents with the mcpServers structure below (macOS example), substituting your real username and the directories you want to expose:

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

On Windows, use escaped backslashes in the paths:

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

1. Restart Claude Desktop. Completely quit the app and reopen it. Claude Desktop reads the config and starts the configured servers on launch.
2. Verify the connection. After restart, an MCP server indicator appears in the bottom-right corner of the conversation input box. Click it to see the tools the server exposes. If the indicator does not appear, see Troubleshooting below.

Understanding the configuration

Each entry under mcpServers is keyed by a friendly name and describes how to launch a local (stdio) server:

• "filesystem" — the display name for the server inside Claude Desktop.
• "command": "npx" — the program used to launch the server. npx runs the Node package without a separate global install.
• "-y" — auto-confirms installation of the server package.
• "@modelcontextprotocol/server-filesystem" — the package name of the server.
• The remaining array entries — arguments passed to the server. For the Filesystem Server, these are the directories it is allowed to access.

To pass secrets such as API keys, add an env object to the server entry. The Windows ${APPDATA} workaround from the official troubleshooting guide is a real example of the env shape:

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

Use a directory you are comfortable letting Claude read and modify: the server runs with your user account's permissions, so it can do anything you can do manually with those files.

Using the server

Once the Filesystem Server is connected, you can ask Claude things like "What files are in my Downloads folder?" or "Save this text to a file on my Desktop." Before any file operation runs, Claude requests your approval, so review each request and deny anything you are not comfortable with.

Transports: local vs. remote

The config above uses the stdio transport — a local process Claude talks to over standard input/output. Claude Code (the CLI, a separate product) also supports remote transports, which is useful context when choosing how a server connects:

For Claude Desktop, stdio via claude_desktop_config.json is the documented local-setup path covered by this guide.

Troubleshooting

Server / tools icon not showing up. Restart Claude Desktop completely. Check claude_desktop_config.json for valid JSON. Make sure every path in the config is absolute, not relative. Then read the logs (below). You can also run the server manually to surface errors:

npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads

Read the logs. MCP logging is written to:

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

mcp.log holds general connection logging; mcp-server-SERVERNAME.log holds a specific server's stderr. To follow recent logs on macOS/Linux:

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

Tool calls failing silently. Check Claude's logs for errors, verify the server runs without errors on its own, and restart Claude Desktop.

Windows ${APPDATA} ENOENT error. If a server's log shows an error referencing ${APPDATA} in a path, add the expanded %APPDATA% value to that server's env block (see the brave-search example above), then relaunch Claude Desktop. Confirm npm is installed globally if npx keeps failing.

Next steps

• Browse official and community servers at the modelcontextprotocol/servers repository.
• Read the official Claude Desktop MCP quickstart at modelcontextprotocol.io/quickstart/user.
• For connecting MCP servers from the Claude Code CLI, see code.claude.com/docs/en/mcp.

• Source repositorygithub.com 2026-07-13T15:19:32-07:00
• Documentationmodelcontextprotocol.io
• Package (SHA-256 pinned)/downloads/mcp/desktop-mcp-setup.mcpb