sodcalculator

10 Tech How-To

How to Set Up MCP Servers on Windows and Mac

Guide 10-53751 · Updated · Step by step

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

  1. 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.json in 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.
  2. 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.
  3. 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 filesystem with a name you choose, and adjust the command and args for your server. For Python-based servers, use python or python3 as the command and the server’s module path as an argument.

  4. For remote servers (HTTP/SSE), use the URL format. Instead of a command, provide a url field:
    {
      "mcpServers": {
        "remote-server": {
          "url": "https://example.com/mcp"
        }
      }
    }

    This works for servers that expose an MCP endpoint over HTTP.

  5. 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.
  6. 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.
  7. 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 npx or 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 npx instead of just npx for some servers. On Mac, npx usually 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 env field in the server entry.

Troubleshooting

  • Server not showing up: Recheck the JSON syntax and that the mcpServers key 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 with cmd /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 with npm 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.json to 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

The whole Tech How-To bed →