This guide walks you through configuring Model Context Protocol (MCP) servers with Claude Desktop on both Windows and macOS. You’ll learn how to add local and remote MCP servers, verify they connect, and fix common setup issues—no prior server experience needed.
What You’ll Need
- Claude Desktop app installed (latest version) on Windows 10/11 or macOS 12+
- Node.js (v18 or newer) installed on your system—needed for many MCP servers
- Python 3.8+ (optional but required for Python-based MCP servers)
- A code editor (like VS Code) to edit configuration files
- Basic familiarity with the command line (Terminal on Mac, Command Prompt or PowerShell on Windows)
Step-by-Step
- Locate the Claude configuration file.
- macOS: Open Finder, press Cmd+Shift+G, and go to
~/.claude.json(or~/Library/Application Support/Claude/claude_desktop_config.jsonin newer versions). - Windows: Press Win+R, type
%APPDATA%\Claude\claude_desktop_config.json, and press Enter. If the file doesn’t exist, create it as a new JSON file.
- macOS: Open Finder, press Cmd+Shift+G, and go to
- Open the config file in a text editor. Use VS Code, Notepad, or any plain-text editor. The file should contain a JSON object with a top-level key named
mcpServers. - Add your first MCP server entry. Each server is defined as a key-value pair under
mcpServers. For a local server run via command line, the entry looks like:{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"] } } }Replace
filesystemwith a name you choose, and adjust the command and args for your server. For Python-based servers, usepythonorpython3as the command and the server’s module path as an argument. - For remote servers (HTTP/SSE), use the URL format. Instead of a command, provide a
urlfield:{ "mcpServers": { "remote-server": { "url": "https://example.com/mcp" } } }This works for servers that expose an MCP endpoint over HTTP.
- Save the file and restart Claude Desktop. After editing, save the JSON file, then completely quit Claude Desktop (right-click the tray/menu bar icon and choose Quit) and relaunch it. The app reads the config on startup.
- Verify the connection. In Claude Desktop, look for a hammer or plug icon (or check Settings → MCP Servers). You should see your server listed with a green dot. Try a prompt like “List available tools” to see the server’s tools.
- Test with a real query. Ask something that uses the server’s capabilities, e.g., for a filesystem server: “List files in my allowed directory.” If it responds correctly, the setup works.
Common Mistakes
- Incorrect JSON syntax: Missing commas, trailing commas, or unquoted keys cause parse errors. Validate your JSON at jsonlint.com before saving.
- Wrong file path: On Windows, using forward slashes or wrong environment variables can point to a non-existent file. Always use the exact path from Step 1.
- Forgetting to install dependencies: Many servers require
npxor Python packages. Run the server command manually in a terminal first to see if it starts without errors. - Not restarting Claude Desktop: The config is only read at launch. A simple refresh won’t pick up changes.
- Using the wrong command for your OS: On Windows, you may need
cmd /c npxinstead of justnpxfor some servers. On Mac,npxusually works directly.
Tips
- Start with one simple server (like the filesystem example) to confirm the process works before adding more.
- Use absolute paths for directories and files in arguments—relative paths can break when the app launches from a different working directory.
- Keep a backup of your config file before making changes, so you can restore it if something goes wrong.
- If you use a version manager like nvm, ensure the Node.js path is accessible to Claude Desktop—sometimes you need to specify the full path to
npx(e.g.,/Users/you/.nvm/versions/node/v20.0.0/bin/npx). - Check the server’s documentation for any required environment variables or API keys, and add them to the
envfield in the server entry.
Troubleshooting
- Server not showing up: Recheck the JSON syntax and that the
mcpServerskey is exactly spelled. Also confirm the file is in the correct location by opening it from the path in Step 1. - Connection error or red dot: Run the server command manually in a terminal. If it errors, fix the command or install missing dependencies. For remote servers, check the URL is reachable (try
curl). - Windows-specific “npx not recognized”: Use the full path to npx.cmd, e.g.,
C:\Program Files\nodejs\npx.cmd. Or wrap the command withcmd /c. - Mac-specific “permission denied”: If using a globally installed package, ensure the binary is executable (
chmod +x). If using npx, try clearing the npm cache withnpm cache clean --force. - Server loads but tools don’t work: Check the server’s logs. On Windows, you can view logs in
%APPDATA%\Claude\logs; on Mac, in~/Library/Logs/Claude. Look for stack traces. - Config file not being read: Some versions of Claude Desktop use a different config location. Search your system for
claude_desktop_config.jsonto find the correct one.
Frequently Asked Questions
Do I need to install Node.js for all MCP servers?
No. Many servers are written in Python or other languages. Check the server’s documentation—if it’s a Python package, you’ll need Python instead. Node.js is only required for npm-based servers.
Can I use MCP servers with Claude.ai (web version)?
No, MCP support is currently available only in the Claude Desktop app, not the web interface.
How do I remove an MCP server?
Delete its entry from the mcpServers object in the config file, save, and restart Claude Desktop.
Is it safe to use third-party MCP servers?
Only use servers from trusted sources, as they can access files or data you grant them. Review the server’s code or documentation before installing.
Can I run multiple MCP servers at once?
Yes, just add multiple entries under mcpServers. Each server will appear separately in Claude Desktop.
What if my server requires authentication?
For remote servers, you can include headers or tokens in the env field (e.g., "env": {"API_KEY": "your-key"}). For local servers, follow the server’s own auth setup.
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- How to Enable Privacy Indicators on Chromebook
- How to Calculate Taxes on Overtime Pay
- VPN Not Working on iPhone? Fixes That Actually Work
- Hide & Unhide Apps on Samsung Phones
- Fix DNS Server Unavailable Error in Windows 11
- Fix iOS 17 Keyboard Not Working Properly