Tutorial5 min readMay 5, 2026

How to Install an MCP Server on Claude Desktop

Claude Desktop reads MCP server configuration from a single JSON file. Add a server entry, fully restart Claude, and the server's tools appear in the conversation. The whole loop takes under five minutes once you know the path.

Goal

Connect any MCP server to Claude Desktop

Time

~5 minutes

Prereq

Claude Desktop installed, Node.js for npx-based servers

Steps

Open claude_desktop_config.json

In Claude Desktop, go to Settings → Developer → "Edit Config". The file opens in your default editor. If the file does not exist yet, Claude creates an empty one. The full path is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows.

Add an mcpServers block

Every server lives under the top-level "mcpServers" key. Each entry is keyed by a name you choose, with a "command" and "args" field that tells Claude how to launch the server process. The example below scopes a Filesystem MCP to a single directory — paths outside the allowlist are rejected.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/code"
      ]
    }
  }
}

Set tokens via env, never via args

For servers that need credentials (GitHub, Slack, Stripe, Postgres), put them in an env block alongside command and args. Tokens in env are passed to the server process at launch but never logged. Tokens hardcoded in args show up in process listings — avoid.

"github": {
  "command": "npx",
  "args": ["@github/github-mcp-server"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
  }
}

Fully quit Claude and reopen

Reload Window does not pick up config changes. Quit Claude completely (Cmd+Q on macOS, File → Exit on Windows) and reopen it. Claude reads the config exactly once on launch — every subsequent edit needs another full restart.

Verify with the hammer icon

At the bottom of the chat input, click the hammer icon. You should see your server name with a green dot and a tool count above zero. If the server is missing or red, jump to the troubleshooting section below — the cause is almost always one of three things.

Smoke-test with a Filesystem prompt

The fastest way to confirm a Filesystem MCP works: ask Claude "list the files in the directory I gave you access to." If the model returns the actual file list, the server is live and the allowlist is correct. If it tries to guess or refuses, the server is not connected.

Sample claude_desktop_config.json

Three popular servers, all free, no API keys needed. Drop this in as a starting point.

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

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/code"
      ]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

When it does not work

Server does not appear at all

Check Settings → Developer → MCP Logs. The most common cause is a typo in the JSON file (a stray comma, missing brace) — Claude logs a parse error and silently ignores the file. Validate the JSON in any editor first if the logs say "could not parse config".

Server shows red status

Open MCP Logs and read the failure line. Three causes account for most reds: (1) the npx package name is wrong or unreachable; (2) a path in args does not exist or has a typo; (3) a required env variable is missing. Fix the line, fully restart Claude, re-check.

Server connected but tool count is zero

The server started but did not register any tools. Usually means a required initialization parameter is missing — check the server's docs for required arguments or env vars. The MCP Inspector (npx @modelcontextprotocol/inspector) is the fastest way to confirm whether the issue is the server or the client.

FAQ

Where is claude_desktop_config.json on macOS and Windows?

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json. The fastest way to open it is Settings → Developer → Edit Config from inside Claude Desktop itself.

Do I need to restart Claude every time I change the config?

Yes. Claude Desktop reads the config once on launch. Reload Window has no effect on MCP servers — you must fully quit (Cmd+Q on macOS) and reopen. The hammer icon picks up the new server count after restart.

Why does my server work in Claude Desktop but not in Claude Code or Cursor?

The config-file shape is slightly different per client. Claude Desktop uses claude_desktop_config.json with an "mcpServers" key. Cursor uses ~/.cursor/mcp.json (also "mcpServers"). Claude Code uses .mcp.json or `claude mcp add`. The server itself is the same — only the wrapper file changes.

Can I share my MCP config across machines?

Yes, but keep secrets out of Git. Most people commit a redacted claude_desktop_config.json template (with empty tokens) to dotfiles, then fill in the real tokens locally on each machine. Some teams use 1Password or Vault MCPs to inject secrets at runtime instead.

Next steps

One server is wired up. Now pick the rest of the stack — the seven MCPs every Claude Desktop user should install.

Best MCPs for Claude Desktop Debug an MCP →