Claude Desktop MCP Setup Guide: Config Locations, Environment Variables & Troubleshooting (2026)

Anthropic's release of the Model Context Protocol (MCP) transformed Claude Desktop from a passive conversational chat window into an autonomous developer command center.

With MCP servers enabled, Claude Desktop can read and write files directly to your local file system, run queries against local PostgreSQL and SQLite databases, inspect GitHub repositories, and execute API calls—all without copy-pasting raw text back and forth.

However, configuring Claude Desktop manually remains a notorious pain point. Because Claude Desktop runs as a GUI application, it does not inherit your interactive shell's $PATH or environment variables, leading to cryptic errors like spawn npx ENOENT or silent client boot crashes when a JSON comma is misplaced.

In this guide, we break down the exact configuration schema, pinpoint config file locations across operating systems, solve the top 4 Claude MCP runtime errors, and demonstrate how to automate your entire setup with zero JSON editing.

Where is claude_desktop_config.json Located?

Claude Desktop stores all registered server configurations in a single JSON file named claude_desktop_config.json.

By default, this file resides in hidden system directories depending on your operating system:

Official Claude MCP Config Schema & Syntax Rules

Claude Desktop expects a top-level object containing a mcpServers dictionary. Each key in this dictionary represents a unique server name, and its value defines the command, execution arguments, and optional environment variables.

Here is a production-ready configuration containing a local SQLite database server and the official GitHub tool:

jsonCopy
{
  "mcpServers": {
    "sqlite-analytics": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/username/data/analytics.db"
      ]
    },
    "github-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_personal_access_token_here"
      }
    }
  }
}

3 Strict Rules to Avoid Claude Crashes:

1. Never Leave Trailing Commas: Standard JSON parsers reject trailing commas after the last array item or dictionary key. If Claude crashes immediately on launch, check for trailing commas.
2. Absolute Paths for SQLite/Filesystem: Relative paths (./data.db or ~/data.db) fail because Claude Desktop's working directory is the application root, not your user home. Always provide absolute paths.
3. Double Backslashes on Windows: On Windows, file paths in JSON must escape backslashes: "C:\\Users\\username\\data.db" or forward slashes "C:/Users/username/data.db".

Fixing 'spawn npx ENOENT' & PATH Inheritance Bugs

The single most common bug reported by Claude Desktop users is:

textCopy
Error: spawn npx ENOENT
    at Process.ChildProcess._handle.onexit (node:internal/child_process:286:19)

Why This Happens:

When you open Terminal or iTerm, your shell profile (.zshrc or .bash_profile) loads NVM, Homebrew, or fnm into your $PATH.

However, when you launch Claude Desktop by clicking its desktop or dock icon, macOS/Windows launches it with a minimalist system $PATH (typically /usr/bin:/bin:/usr/sbin:/sbin). Because /opt/homebrew/bin or your NVM Node directory is omitted, Claude cannot find the npx or uvx executable.

The Solution: Use the Full Binary Path

Find the absolute path to your executable in your terminal:

bashCopy
# On macOS / Linux
which npx
# Returns: /opt/homebrew/bin/npx (or ~/.nvm/versions/node/v20.x/bin/npx)

which uvx
# Returns: ~/.cargo/bin/uvx

Then update your claude_desktop_config.json to reference the absolute binary:

jsonCopy
{
  "mcpServers": {
    "filesystem": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop"
      ]
    }
  }
}

Passing Environment Variables & Secrets Safely to Tools

Many MCP servers (like GitHub, Brave Search, Postgres, and Linear) require API keys or database connection strings.

Inside claude_desktop_config.json, supply them under the env key:

jsonCopy
{
  "mcpServers": {
    "postgres-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://postgres:secretpassword@localhost:5432/production"
      ],
      "env": {
        "DEBUG": "mcp:*"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "BSA_your_brave_api_token"
      }
    }
  }
}

Essential Free MCP Servers for Claude Desktop

Here are the top 4 essential servers tested for stability with Claude Desktop:

1. Filesystem MCP: Gives Claude read/write access to chosen directories on your workstation.
2. PostgreSQL MCP: Inspect table schemas, run EXPLAIN queries, and debug SQL syntax.
3. GitHub MCP: Search code, create pull requests, read issues, and inspect repository commits.
4. Brave Web Search: Empowers Claude with real-time web search capabilities without paywalls.

The 1-Click Automated Alternative: AIStoreHub CLI

Editing nested JSON files manually and resolving binary paths is fragile.

The open-source AIStoreHub CLI (pip install aistorehub) automates Claude Desktop configuration with a single command:

bashCopy
# 1. Install the CLI
pip install aistorehub

# 2. Inject verified MCP server directly into Claude Desktop
aihub mcp install community/postgres-mcp --client claude

# 3. View all active servers in Claude
aihub list --client claude

What AIStoreHub CLI Does Automatically:

1. Detects Your Claude Config File: Automatically locates the file on macOS or Windows without requiring manual directory searching.
2. Path Auto-Resolution: Resolves npx and uvx to their absolute system binary paths to prevent spawn ENOENT crashes.
3. Timestamped Backups: Generates a safety backup (claude_desktop_config.backup-<timestamp>.json) before modifying a single line.
4. Syntax Linter: Validates JSON syntax before writing to prevent Claude launch crashes.

Explore hundreds of verified MCP servers, community tools, and autonomous agents in the AIStoreHub Registry.