Configuring Claude Desktop for MCP

This comprehensive guide covers everything you need to know about configuring Claude Desktop to work with MCP servers, from basic setup to advanced configuration options and best practices.

Configuration File Overview

Claude Desktop uses a JSON configuration file to manage MCP server connections. This file tells Claude which servers to connect to, how to launch them, and what permissions they should have.

Configuration File Location

The configuration file location varies by operating system:

Basic Configuration Structure

The configuration file has a simple structure with an mcpServers object containing your server definitions:

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["argument1", "argument2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Configuration Fields Explained

server-name

A unique identifier for your server. Use descriptive names like "filesystem" or "postgres-production".

command

The executable to run. Common values are "npx", "uvx", "python", or a full path to a binary.

args

An array of arguments passed to the command. Each argument is a separate string.

env (optional)

Environment variables to set for the server. Used for API keys, database URLs, etc.

Common Server Configurations

Filesystem Server

Allows Claude to read and write files in specified directories:

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

Git Server

Provides Git repository operations:

{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-git",
        "--repository",
        "/Users/yourname/projects/myrepo"
      ]
    }
  }
}

PostgreSQL Server

Connects to a PostgreSQL database:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://username:password@localhost:5432/dbname"
      ]
    }
  }
}

GitHub Server

Integrates with GitHub using a personal access token:

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

Advanced Configuration Options

Multiple Directory Access

You can grant access to multiple directories by adding them to the args array:

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

Environment Variables

Use environment variables for sensitive data like API keys:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-slack"
      ],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_TEAM_ID": "T1234567"
      }
    }
  }
}

Python-Based Servers

For Python servers, use uvx or python:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/yourname/data/mydb.sqlite"
      ]
    }
  }
}

Custom Binary Paths

For locally built or custom servers, specify the full path:

{
  "mcpServers": {
    "custom-server": {
      "command": "/Users/yourname/mcp-servers/my-server/bin/server",
      "args": ["--config", "/path/to/config.json"]
    }
  }
}

Complete Multi-Server Example

Here's a realistic configuration with multiple servers for a development workflow:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Projects"
      ]
    },
    "git": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-git",
        "--repository",
        "/Users/yourname/Projects/myapp"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    },
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      }
    }
  }
}

Configuration Best Practices

1. Use Descriptive Server Names

Choose names that clearly indicate what each server does and which environment it connects to:

• ✅ Good: "postgres-production", "filesystem-projects"
• ❌ Bad: "server1", "db"

2. Secure Sensitive Data

Never commit configuration files with secrets to version control:

• Use environment variables for API keys and passwords
• Consider using a secrets manager for production environments
• Keep a template config file without secrets in your repository
• Add the actual config file to .gitignore

3. Limit File System Access

Only grant access to directories that Claude actually needs:

• ✅ Good: Specific project directories
• ❌ Bad: Your entire home directory or system root

4. Test Configuration Changes

After modifying the configuration:

1. Save the file
2. Completely quit Claude Desktop
3. Restart Claude Desktop
4. Test that servers are working correctly

5. Keep Backups

Before making major changes, backup your working configuration:

Troubleshooting Configuration Issues

Invalid JSON Syntax

If Claude Desktop won't start or servers don't load, check for JSON errors:

• Missing or extra commas
• Unmatched brackets or braces
• Unescaped backslashes in Windows paths (use \\\\ or /)
• Missing quotes around strings

Use a JSON validator like jsonlint.com to check your configuration.

Server Won't Start

If a server fails to start:

• Verify the command is in your PATH
• Check that all required dependencies are installed
• Try running the command manually in terminal
• Look for typos in the server package name
• Check Claude Desktop logs for error messages

Permission Errors

If you see permission denied errors:

• Verify directory paths exist and are accessible
• Check file permissions on the directories
• On macOS, grant Full Disk Access to Claude Desktop in System Preferences
• Ensure you're not trying to access system-protected directories

Environment Variables Not Working

If environment variables aren't being recognized:

• Check for typos in variable names
• Ensure values are properly quoted strings
• Restart Claude Desktop after changes
• Try setting variables in your shell profile as a fallback

Platform-Specific Notes

macOS

• Use forward slashes in paths: /Users/name/folder
• Grant Full Disk Access if accessing protected directories
• Configuration file is hidden by default (use Cmd+Shift+. to show)

Windows

• Use forward slashes or escaped backslashes: C:/Users/name or C:\\\\Users\\\\name
• Environment variables use %VARIABLE% syntax in paths
• Some servers may require running Claude Desktop as administrator

Linux

• Use standard Unix paths: /home/username/folder
• Ensure Node.js/Python are in your PATH
• Check file permissions with ls -la

Next Steps