Skip to content

claude-desktop-mcp.md

Latest commit

 

History

History
98 lines (76 loc) · 3.68 KB

claude-desktop-mcp.md

File metadata and controls

98 lines (76 loc) · 3.68 KB
Raw

Claude Desktop & MCP Servers

How to install Claude Desktop, add MCP servers, and inspect / validate / repair MCP configuration files. This is the most common and most mechanical task — high success rate when done carefully.

Config file locations

MCP-capable clients each keep their own config. Find the right one first.

Client macOS Windows
Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json
Claude Code (per project) <project>/.claude/mcp.json or .mcp.json same
LM Studio ~/.lmstudio/mcp.json %USERPROFILE%\.lmstudio\mcp.json
Cursor ~/.cursor/mcp.json %USERPROFILE%\.cursor\mcp.json

If the file doesn't exist yet, create it with a minimal valid skeleton:

{ "mcpServers": {} }

Anatomy of an MCP server entry

A stdio server entry has a launch command, args, and optional env:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@scope/some-mcp-server"],
      "env": { "SOME_API_KEY": "..." }
    }
  }
}

Notes:

  • On Windows, npx sometimes must be invoked as cmd /c npx ... — if a server fails to launch on Windows but works on macOS, try wrapping the command.
  • Use absolute paths for local scripts; ~ is not expanded inside JSON.
  • Secrets belong in env here (or the server's own config), never pasted into chat.

Add a server end-to-end

  1. Confirm prerequisites. Most MCP servers need Node (check node -v; many need 18+). Some need Python or Docker. Install the runtime if missing.
  2. Back up the config (claude_desktop_config.json → claude_desktop_config.json.bak).
  3. Add the server block under mcpServers. Preserve existing entries.
  4. Validate the JSON (parse it; check for trailing commas, unescaped backslashes in Windows paths, missing quotes).
  5. Fully restart the client. Claude Desktop must be quit and reopened — a window reload is not enough.
  6. Verify. Confirm the server appears and its tools are listed. If the client shows a "failed" server, read its MCP log.

Inspect, validate, repair (the core job)

When a user says MCP "isn't working," diagnose in this order:

  1. Read the config file and pretty-print it. Most breakages are here.
  2. Validate JSON. The frequent culprits:
    • trailing comma after the last entry
    • single backslashes in Windows paths (need \\ or forward slashes)
    • smart quotes from copy-paste instead of straight quotes
    • a server block pasted at the wrong nesting level
  3. Check the launch command resolves — does command exist on PATH? Run it manually in a terminal to see the real error.
  4. Check credentials — is the required env key present and valid?
  5. Repair, back up first, restart the client, then re-verify.

Connection health check

Separate the three failure classes so you fix the right thing:

  • Config typo → client shows the server as failed immediately on start; the JSON or command is wrong. Fix the file.
  • Server down / crashes → server starts then exits; running the command manually reproduces the crash. Fix deps/runtime.
  • Auth failure → server starts and lists tools, but calls fail with 401/403. Fix the API key/token.

Claude Desktop install

If Claude Desktop itself isn't installed, point the user to the official download and confirm the app launches before touching MCP config. Don't side-load from unofficial mirrors.

Safety

  • Only add MCP servers from sources the user trusts; an MCP server runs with the user's privileges.
  • Back up before editing; redact secrets in summaries; restart the client to apply changes.