How to Install MCP Servers on Windows, macOS & Linux Without Wasting 3 Hours on JSON Errors

1. The Installation Trap No One Warns You About

You found the perfect MCP server on GitHub. The README looks decent. You copy the JSON snippet, paste it into claude_desktop_config.json, restart Claude Desktop… and nothing works. The server doesn't appear. Claude can't see it. You spend the next hour checking paths, reinstalling Node.js, and questioning your entire career.

I know this because I've lived it – on Windows, macOS, and Linux alike. I founded mcpindex.dev after helping thousands of developers install MCP servers across every platform — and I've catalogued the exact failure patterns that waste their time.

Here's what nobody tells you: MCP server installation isn't hard because the protocol is complex. It's hard because every client uses a different registration method, the error messages are cryptic, and one missing restart can make you think the whole thing is broken.

By the end of this guide, you'll have the exact commands, the right config templates, and a free premium cheat sheet that eliminates these problems permanently – no matter your operating system.

2. Why Most "Quick Setup Guides" Actually Cost You 3 Hours

The average developer loses 3 hours on their first MCP server installation. Not because the servers are hard to install, but because the documentation is fragmented across client-specific docs, outdated forum posts, and incomplete README files. This happens on Windows just as often as macOS.

3. The Real Difference Between Claude Desktop, Cursor, and VS Code

Before we dive into commands, understand this: MCP server registration is fundamentally different across clients.

4. The Standard MCP Installation Flow (Works on Windows, macOS, Linux)

1. 1

   Choose the MCP server to install

   Start with an official server. GitHub MCP Server is the best first install; Context7 is the best second.

2. 2

   Install dependencies

   If the server uses npx, install Node.js first. For remote endpoints, confirm the URL and credentials.

3. 3

   Register the server in your client

   Claude Desktop: edit claude_desktop_config.json. Cursor: use MCP Settings UI. Claude Code/VS Code: use claude mcp add.

4. 4

   Add environment variables

   Paste API keys or tokens exactly as required. A single typo breaks the connection.

5. 5

   Restart the client completely

   Not reload — full quit and reopen. On Windows, close the application window and relaunch. This step alone fixes 40% of issues.

6. 6

   Test with a simple prompt

   Ask Claude to perform a task that clearly requires the server, like listing your GitHub repositories.

5. Installing on Claude Desktop (Windows & macOS)

Config file locations: macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

Save the file, fully restart Claude (Cmd+Q on macOS, or close window on Windows), then test with a prompt like "List my GitHub repositories".

6. Installing on Cursor, Claude Code, and VS Code

claude mcp add github -- npx -y @github/github-mcp-server

7. The 5 Errors That Break Every MCP Installation (And Their Exact Fixes)

9. Conclusion: From Frustration to Connected in Under 15 Minutes

Three things that will save you the most time, regardless of your OS:

• 1. Know your client's registration method — don't mix JSON with UI.
• 2. Validate your JSON. One comma mistake breaks everything silently.
• 3. Always restart the client completely. This alone solves 40% of problems.

Don't download the cheat sheet if you enjoy debugging invisible JSON errors for 3 hours. But if you want the exact commands, error fixes, and templates that have saved thousands of developers from installation hell, grab it now while it's still free.

Best first MCP servers to install

MCP server security tips before you install

Frequently asked questions (2026)