Claude Desktop MCP: Complete Setup Guide (2026)

What MCP Does in Claude Desktop

MCP (Model Context Protocol) lets Claude Desktop connect to external tools and data sources. Without MCP, Claude can only work with text you paste into the conversation. With MCP, it can read files from your machine, push commits to GitHub, execute database queries, and fetch live web content.

The architecture is simple. Claude Desktop is the host. Each MCP server is a separate process running on your machine (or a remote server). When Claude wants to read a file, it sends a JSON-RPC call to the filesystem MCP server. The server reads the file and returns the contents. Claude never has direct file access. Every action routes through the server and requires your approval.

The Config File

The config file is claude_desktop_config.json. Its location depends on your OS:

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

To open it: Claude Desktop menu bar (not the window) → Settings → Developer tab → Edit Config. If the file does not exist yet, Claude creates it. On macOS you can also open it directly in Terminal:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

The file has one top-level key: mcpServers. Each child key is a server name (you choose it). Each server has a command and args. Optional: env for environment variables.

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@scope/server-package", "arg1", "arg2"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

Add Your First Server (Filesystem)

The filesystem server is the right starting point. It requires no API keys, runs via npx (no install), and gives Claude read and write access to directories you specify. Claude can read files, create new ones, move folders, and search by name or content.

Prerequisites: Node.js must be installed. Check with node --version. If missing, download the LTS version from nodejs.org.

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

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

After saving, completely quit Claude Desktop (not just close the window) and reopen it. The MCP server indicator appears in the bottom toolbar of any conversation. Click the slider icon to see available tools. The filesystem server provides: read_file, write_file, list_directory, create_directory, move_file, and search_files.

Every tool call requires your approval. Claude shows you what it wants to do before executing. You can approve once, approve for the session, or deny.

Popular MCP Servers to Add

These are the servers with the best signal-to-noise ratio for Claude Desktop. Each one is maintained by either Anthropic or the service it connects to.

Multi-Server Config Example

You can run as many servers as you need. Claude Desktop launches them all on startup. Here is a practical config for a developer workflow: filesystem access, GitHub integration, web fetching, and Brave Search.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Desktop",
        "/Users/yourname/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Some servers are Python-based and use uvx instead of npx. Install uv first (curl -LsSf https://astral.sh/uv/install.sh | sh on macOS/Linux). Then the command is uvx and args start with the package name.

{
  "mcpServers": {
    "my-python-server": {
      "command": "uvx",
      "args": ["mcp-server-package-name"]
    }
  }
}

Claude Desktop vs Claude Code MCP

Claude Desktop (the chat app at claude.ai) and Claude Code (the terminal-based coding agent) both support MCP, but they are configured differently and behave differently.

The config structure is identical between the two. If you have a server working in Claude Desktop, you can copy the same JSON entry into your Claude Code settings and it will work there too. The key difference is the approval workflow: Claude Desktop asks before every action, while Claude Code lets you pre-approve categories of tools.

Troubleshooting

Most MCP issues in Claude Desktop fall into four categories. Start with the logs.

Reading the Logs

Claude Desktop writes MCP logs to:

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

Two log files matter: mcp.log (connection events and failures) and mcp-server-SERVERNAME.log (stderr from each server). Follow them in real time while restarting Claude Desktop:

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

Testing a Server Directly

Before adding a server to Claude Desktop, verify it runs correctly in your terminal. This separates config issues from server issues:

npx -y @modelcontextprotocol/server-filesystem /Users/yourname/Desktop

If the command errors, fix the server issue first. If it hangs silently waiting for input, it started correctly (it is waiting for JSON-RPC messages on stdin). Press Ctrl+C to exit.

Chrome DevTools in Claude Desktop

For deeper debugging, enable Chrome DevTools inside Claude Desktop. Create a file:

echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json

Then press Command+Option+Shift+I inside Claude Desktop. The Console panel shows client-side errors. The Network panel shows MCP message traffic.

Frequently Asked Questions

Where is the Claude Desktop config file?

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json. Open it from Claude Desktop via Settings → Developer tab → Edit Config.

How do I add an MCP server to Claude Desktop?

Edit claude_desktop_config.json and add an entry under mcpServers. Each entry needs command (the process: usually npx or uvx) and args (the package name and any arguments). Save the file, quit Claude Desktop completely, and reopen it. The server should appear in the toolbar.

What MCP servers work best with Claude Desktop?

Start with @modelcontextprotocol/server-filesystem for local file access (no API key). Add @modelcontextprotocol/server-github for code search and PR workflows (requires GitHub token). Add @modelcontextprotocol/server-memory for persistent context across conversations. These three cover most everyday Claude Desktop use cases.

Why is my MCP server not showing up?

In order: (1) check mcp.log at ~/Library/Logs/Claude/, (2) validate your JSON has no syntax errors, (3) confirm Node.js is installed, (4) confirm all file paths are absolute not relative, (5) test the server command directly in a terminal to isolate whether the issue is the server or the config.

How is Claude Desktop MCP different from Claude Code MCP?

Claude Desktop is the chat app. Claude Code is the terminal coding agent. Both support MCP using the same mcpServers config structure, but config files live in different locations. Claude Desktop requires explicit approval for each tool call. Claude Code can be configured to auto-approve categories of tools. A server config that works in one works in the other.

Can I use Python MCP servers in Claude Desktop?

Yes. Install uv first, then use uvx as the command instead of npx. Python servers from the community (on PyPI) follow the pattern: "command": "uvx", "args": ["package-name"]. No separate pip install needed.

How do I pass API keys to MCP servers?

Use the env key in the server config object. Claude Desktop injects these as environment variables when it starts the server process. Do not put API keys in the args array since those appear in process listings. Example: "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_abc123" }.