claude_desktop_config.json: Location, Setup, and Fix Guide (2026)

The claude_desktop_config.json file controls which MCP servers Claude Desktop connects to. This guide covers the exact file path on every OS, a minimal working config, the most common errors, and how to verify your setup.

File location by operating system

Claude Desktop creates this file automatically on first launch. If you do not see it, open Claude Desktop once, then check again.

macOS

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

Windows

%APPDATA%\Claude\claude_desktop_config.json

Typically: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

Minimal working config

A valid config file needs one top-level mcpServers object. Each key is a server name; each value describes how to connect.

claude_desktop_config.json (stdio transport)

{
  "mcpServers": {
    "my-local-server": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

claude_desktop_config.json (streamable-http transport)

{
  "mcpServers": {
    "hooklayer": {
      "type": "streamable-http",
      "url": "https://hooklayer.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer hl_live_YOUR_KEY_HERE"
      }
    }
  }
}

Common errors and fixes

Trailing comma in JSON

JSON does not allow trailing commas. A comma after the last property in an object or array breaks parsing silently. Validate your file at jsonlint.com before saving.

Relative paths in "command"

Claude Desktop runs with a minimal PATH. Using npx without the full path often fails. Use /usr/local/bin/npx on macOS or C:\\Program Files\\nodejs\\npx.cmd on Windows. Run which npx (macOS/Linux) or where npx (Windows) to find the full path.

Not fully restarting Claude Desktop

Closing the window does not restart the app on macOS. Right-click the dock icon and select Quit, then reopen. On Windows, use the system tray icon to exit completely.

Wrong file or duplicate config

Some editors create backup files like claude_desktop_config.json.bak. Make sure you are editing the exact filename above, not a copy.

How to verify your config

Step 1: Restart Claude Desktop

Fully quit and reopen the app.

Step 2: Look for the hammer icon

In the bottom-left of the chat input, a hammer icon appears when MCP servers are connected. If it is missing, your config has an error.

Step 3: Click the hammer

It lists every connected server and its available tools. Confirm your server name and tool count match expectations.

Adding Hooklayer to your config

Hooklayer is a hosted MCP server (streamable HTTP), so there is nothing to install locally. Paste this block into your mcpServers object:

Add to claude_desktop_config.json

{
  "mcpServers": {
    "hooklayer": {
      "type": "streamable-http",
      "url": "https://hooklayer.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer hl_live_YOUR_KEY_HERE"
      }
    }
  }
}

Get your free API key (50 credits, no card) at hooklayer.dev/auth/signup. After restarting Claude Desktop, the hammer icon will show 8 Hooklayer tools: analyze_account, score_hook, viral_remix, trend_pulse, find_viral_template, match_voice, predict_virality, and search_videos.

Frequently asked questions

Where is claude_desktop_config.json located?

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json (typically C:\Users\YourName\AppData\Roaming\Claude\). On Linux: ~/.config/Claude/claude_desktop_config.json.

Why does my MCP server not show up after editing config.json?

Three common causes: (1) JSON syntax error, even a trailing comma breaks parsing. Validate at jsonlint.com. (2) You edited the wrong file. Use the exact paths above. (3) You did not fully restart Claude Desktop. Quit (not just close the window) and reopen.

Do I need to use absolute paths in the config?

Yes. Claude Desktop runs with a minimal PATH, so commands like "npx" or "node" often fail unless you use the full executable path. On macOS, run "which npx" to find it (typically /usr/local/bin/npx). On Windows, use the full path like C:\Program Files\nodejs\npx.cmd.

How do I verify my MCP server is connected?

After restarting Claude Desktop, look for the hammer icon in the bottom-left of the chat input. Click it to see connected MCP servers and their available tools. If the hammer icon is missing, your config has an error.

Can I add multiple MCP servers in one config?

Yes. Each server gets its own key inside the "mcpServers" object. They all load in parallel when Claude Desktop starts.

What is the difference between stdio and streamable-http transport?

Stdio transport runs a local process (command + args). Streamable-http connects to a remote server URL with optional headers. Hosted MCP servers like Hooklayer use streamable-http so there is nothing to install locally.