How to Set Up Your First MCP Server in Claude Desktop

2026-08-22 · by bixzell

Anthropic’s Claude Desktop application was the flagship client for the Model Context Protocol (MCP). By connecting MCP servers to Claude Desktop, you transform Claude from a standalone chat model into an assistant that can query local SQLite databases, inspect folders on your filesystem, fetch live documentation, and interact with external APIs.

Setting up your first server takes less than five minutes, but developers frequently stumble over subtle JSON syntax errors, macOS GUI environment variables, and missing node binaries. This guide walks you through the exact setup process from scratch.

Prerequisites

Before configuring Claude Desktop, ensure you have:

  1. Claude Desktop installed (macOS or Windows). A Claude Pro, Team, or Enterprise plan is typically recommended for heavy tool use.
  2. Node.js (v18+) and/or Python (3.10+) installed on your system.
  3. Recommended package runners: npx (bundled with npm) or uv / uvx (for fast Python-based MCP execution).

Step 1: Locate claude_desktop_config.json

Claude Desktop reads all server definitions from a single JSON configuration file. Its location depends on your operating system:

macOS

Open your terminal and check:

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

Quick shortcut: In Claude Desktop, click Claude in the menu bar → Settings… → Developer tab → click Edit Config. This opens the exact file in your default code editor.

Windows

Open File Explorer and navigate to:

%APPDATA%\Claude\claude_desktop_config.json

(Typically C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)

If the file does not exist, create it with an empty server object:

{
  "mcpServers": {}
}

Step 2: Add starter MCP servers

Below are three reliable starter servers covering remote web tools, local file access, and database querying. You can copy and paste any combination into your mcpServers block.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Projects"
      ]
    },
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/username/data/analytics.db"
      ]
    },
    "exa": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.exa.ai/mcp"
      ]
    }
  }
}

Windows Note: Replace forward slashes with double backslashes for local paths (e.g. C:\\Users\\YourName\\Desktop).

What each starter server does:

  1. @modelcontextprotocol/server-filesystem: Gives Claude read and write access strictly to the directories you whitelist as arguments. Claude can read code files, summarize markdown notes, and write output files directly to your desktop.
  2. mcp-server-sqlite: Allows Claude to inspect database schemas, write SQL queries, and summarize data directly from a local .sqlite or .db file using uvx.
  3. mcp-remote / Exa: Bridges remote Streamable HTTP MCP endpoints into Claude Desktop so Claude can search the web without local server dependencies.

Step 3: Completely restart Claude Desktop

Saving claude_desktop_config.json does not hot-reload running servers. You must completely terminate and relaunch the application:

  • macOS: Press Cmd + Q (closing the chat window does not quit the background helper).
  • Windows: Right-click the Claude icon in the system tray and select Quit, then reopen Claude.

Step 4: Verify in the chat interface

Once Claude restarts, look at the bottom right corner of the chat input box. You should see a small hammer icon (🔨).

Clicking the hammer icon opens the active tools drawer, listing every tool exposed by your configured servers (e.g. read_file, list_directory, read_query, web_search_exa).

Try sending a prompt to verify execution:

“What files are currently on my Desktop?” or “List all tables in my SQLite database.”

Claude will ask for your confirmation before running tools that read or modify files, ensuring you maintain full control over tool invocations.

The #1 Gotcha: GUI applications do not inherit your shell PATH

The single most common bug when setting up Claude Desktop is:

“Server exited with code 1” or “Command not found: npx / uvx”

Why this happens

When you run commands in your terminal (like zsh or bash), your shell loads environment variables from ~/.zshrc or ~/.bash_profile. However, macOS GUI applications launched from Finder or Spotlight do not inherit your terminal’s PATH. If you installed Node via NVM, Homebrew, or fnm, Claude Desktop cannot locate npx or node.

How to fix it

Replace bare command names with their absolute paths:

Find your binary path in terminal:

which npx
# Returns e.g.: /opt/homebrew/bin/npx or /Users/username/.nvm/versions/node/v22.12.0/bin/npx
which uvx
# Returns e.g.: /Users/username/.cargo/bin/uvx

Update your claude_desktop_config.json:

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

How to inspect logs and debug failures

If a server fails to start or the hammer icon does not appear, check Claude Desktop’s log files:

macOS Log Path

tail -n 50 -f ~/Library/Logs/Claude/mcp*.log

Windows Log Path

%APPDATA%\Claude\logs\mcp*.log

You can also open Claude Desktop’s developer console by pressing Cmd + Option + I (macOS) or Ctrl + Shift + I (Windows). The Console tab will report MCP client handshake failures, JSON parsing errors, and transport crashes in real time.

Next steps

Once your base Claude Desktop configuration is working: