Claude Desktop MCP Setup Guide

What is Claude Desktop + MCP?

Claude Desktop is Anthropic's official desktop application for Claude AI. By default, Claude can only answer questions using its training data — it can't access your files, databases, or APIs.

MCP (Model Context Protocol) is an open protocol that connects Claude to external tools. Think of it as a universal USB port for AI integrations. Once you add MCP servers to Claude Desktop, you can ask Claude to:

• Read and edit files on your computer
• Query your PostgreSQL/MySQL databases
• Create GitHub issues and pull requests
• Search the web with Brave or Google
• Manage your Notion workspace
• ...and 100+ more integrations

Prerequisites

Step 1: Find Your Claude Desktop Config File

Claude Desktop stores its configuration in a JSON file. The location depends on your operating system:

If the file doesn't exist, create it manually. Claude Desktop will read it on next launch.

Step 2: Add Your First MCP Server

Let's add the Filesystem server as your first MCP integration. This lets Claude read and write files on your computer.

Create or Edit the Config File

Open claude_desktop_config.json in a text editor and add this configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents",
        "/Users/yourname/Projects"
      ]
    }
  }
}

Understanding the Config Structure

Let's break down what each field means:

{
  "mcpServers": {           // All MCP servers go here
    "filesystem": {          // Server name (you choose this)
      "command": "npx",      // How to launch the server
      "args": [              // Arguments passed to the command
        "-y",                // Auto-confirm npx installs
        "@modelcontextprotocol/server-filesystem",  // npm package
        "/path/to/dir"       // Server-specific arguments
      ]
    }
  }
}

Step 3: Restart Claude Desktop

For changes to take effect, you must fully restart Claude Desktop:

Step 4: Test the Connection

Now let's verify that Claude can actually use your new filesystem server. Try these example prompts:

If Claude successfully executes these tasks, congratulations! Your first MCP server is working.

Adding More Servers

Now that you have the filesystem server working, let's add more capabilities. You can add multiple servers to the same config file.

Example: Multiple Servers Configuration

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents",
        "/Users/yourname/Projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Notice how each server is configured separately with its own command, args, and optionally env (for API keys and environment variables).

Popular MCP Servers to Try

Troubleshooting Common Issues

Error: "Server failed to start" (Code -32000)

This is the most common error. Causes and solutions:

• Invalid JSON syntax: Use a JSON validator to check your config file. Common issues: missing commas, trailing commas, unescaped backslashes in Windows paths.
• Wrong file paths: Ensure all directory paths exist and use absolute paths (not relative paths like ./Documents).
• Node.js not installed: Install Node.js from nodejs.org if using npm-based servers.
• Server package doesn't exist: Double-check the npm package name in args.

Error: "Server not found" or No Tools Appearing

• Config file in wrong location: Verify you edited the correct file for your OS (see Step 1).
• Didn't restart Claude: You must fully quit (Cmd+Q or Exit from tray) and reopen.
• Server name typo: Check that the server name in mcpServers matches documentation.

Error: "Permission denied" or "Access forbidden"

• Filesystem server: Ensure the paths you specified have read/write permissions.
• API-based servers (GitHub, Notion, etc.): Verify your API token/key is correct and has the necessary permissions/scopes.
• Environment variables not set: Check that env keys match what the server expects (case-sensitive).

Windows: Backslash Path Issues

Windows uses backslashes (\) in file paths, but JSON requires them to be escaped as \\:

// ❌ WRONG (single backslash)
"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\Users\John\Documents"]

// ✅ CORRECT (escaped backslashes)
"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\John\\Documents"]

// ✅ ALSO CORRECT (forward slashes work too!)
"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/John/Documents"]

Checking Logs for Errors

Claude Desktop writes MCP server logs that can help diagnose issues:

Best Practices

Security Considerations

• Limit filesystem access: Only grant access to directories Claude actually needs. Avoid giving access to your entire home directory or root filesystem.
• Protect API keys: Never commit claude_desktop_config.json to Git if it contains API tokens. Use environment variables or a secrets manager.
• Use read-only database users: For database servers, create a limited user account with only SELECT permissions (no INSERT/UPDATE/DELETE) unless necessary.
• Review tool permissions: Before enabling an MCP server, check what tools it exposes. Click the 🔌 icon in Claude Desktop to see all available tools.
• Rotate tokens regularly: Set API token expiration dates and rotate them periodically.

Using Environment Variables (Advanced)

Instead of hardcoding API keys in the config file, you can reference environment variables:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"  // Reads from environment
      }
    }
  }
}

Then set the environment variable before launching Claude Desktop:

# macOS/Linux
export GITHUB_TOKEN="ghp_your_token"
open -a Claude

# Windows (PowerShell)
$env:GITHUB_TOKEN="ghp_your_token"
Start-Process "Claude"

Sandboxing with Docker (Advanced)

For maximum security, you can run MCP servers in Docker containers to isolate them from your system. This is particularly useful for untrusted community servers.

Next Steps

Now that you have Claude Desktop connected to MCP servers, explore these resources: