How to Set Up MCP Servers in Claude Desktop: Complete 2025 Guide

What You'll Learn

This guide teaches you how to set up MCP (Model Context Protocol) servers in Claude Desktop—the technology that lets Claude access files, databases, APIs, and external tools. By the end, you'll have working MCP servers that dramatically expand what Claude can do for you.

Two setup methods covered:

Desktop Extensions (5 minutes) - One-click installation, automatic updates
Manual Configuration (15-45 minutes) - Full control, custom servers

New to MCP? The Model Context Protocol is an open standard by Anthropic that enables AI assistants to securely interact with external data sources and tools. Think of MCP servers as plugins that give Claude superpowers.

Quick Start: Your First MCP Server
Prerequisites
Method 1: Desktop Extensions (Recommended)
Method 2: Manual Configuration
Popular MCP Server Configurations
Troubleshooting Common Issues
Security Best Practices
Next Steps
FAQ

Quick Start: Your First MCP Server

Want to get started immediately? Here's the fastest path to a working MCP server:

Option A: Desktop Extension (Easiest - 2 minutes)

Open Claude Desktop → Settings (gear icon) → Extensions
Search for "Filesystem"
Click Install → Grant permissions
Start a new chat and ask: "List the files in my Documents folder"

Option B: Manual Setup (5 minutes)

Step 1: Create or edit the config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Step 2: Add this configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/folder"]
    }
  }
}

Step 3: Restart Claude Desktop completely (quit and reopen)

Step 4: Look for the MCP server indicator (hammer icon) in the chat input area

Prerequisites

Before setting up MCP servers, verify your system meets these requirements:

System Requirements

| Requirement | Minimum | Recommended | |-------------|---------|-------------| | Claude Desktop | Latest version | Latest version with Extensions | | Operating System | Windows 10, macOS 10.15, Ubuntu 18.04 | Windows 11, macOS 14+, Ubuntu 22.04 | | Node.js | v18.0.0 | v20.0.0+ (LTS) | | Python | 3.8+ (for Python servers) | 3.11+ | | Disk Space | 500 MB | 2 GB | | RAM | 4 GB | 8 GB+ |

Verify Your Installation

Open a terminal and run these commands:

# Check Node.js version
node --version
# Expected: v18.0.0 or higher

# Check npm version
npm --version
# Expected: 8.0.0 or higher

# Check Python (if using Python-based servers)
python --version
# Expected: Python 3.8.0 or higher

# Find Node.js path (important for manual config)
# macOS/Linux:
which node
# Windows:
where node

Missing Node.js? Download from nodejs.org (LTS version recommended).

Method 1: Desktop Extensions (Recommended)

Desktop Extensions are the easiest way to install MCP servers in 2025. They work like browser extensions—one-click install, automatic updates, and managed security.

Step 1: Access the Extensions Marketplace

Open Claude Desktop
Click the Settings icon (gear, bottom-left)
Select the Extensions tab
Click Browse Extensions

Claude Desktop Extensions Interface

Step 2: Browse Available Extensions

Extensions are organized by category:

Productivity

| Extension | Description | Setup Time | |-----------|-------------|------------| | Filesystem | Read and manage local files | 1 min | | Google Drive | Access Drive documents | 2 min | | Notion | Query Notion databases | 2 min | | Slack | Send messages, search channels | 3 min |

Development

| Extension | Description | Setup Time | |-----------|-------------|------------| | GitHub | Repository and code management | 2 min | | PostgreSQL | Database queries | 3 min | | Docker | Container management | 2 min | | Git | Version control operations | 1 min |

Data & Analytics

| Extension | Description | Setup Time | |-----------|-------------|------------| | SQLite | Local database queries | 1 min | | Pandas | Data analysis | 2 min | | Google Sheets | Spreadsheet operations | 3 min |

Tip: See our Top 10 MCP Servers 2025 Review for detailed comparisons and ratings.

Step 3: Install an Extension

Let's install the GitHub extension as an example:

Search for "GitHub" in the Extensions marketplace
Click "Install" on the GitHub MCP Extension
Review permissions the extension requests:
- Repository read/write access
- Issue and PR management
- Code search capabilities
Click "Authorize" to proceed
Authenticate with GitHub when prompted (OAuth flow)

Step 4: Configure Extension Settings

After installation:

Click Configure next to the installed extension
Authenticate with the service (GitHub, Google, etc.)
Grant permissions for repository/file access
Test the connection using the built-in validation

Your extension configuration is stored securely:

{
  "extensionId": "github-mcp",
  "version": "1.2.0",
  "status": "active",
  "permissions": ["repo:read", "issues:write", "pull_requests:write"]
}

Step 5: Verify Installation

Test your GitHub extension:

Start a new conversation in Claude Desktop
Ask Claude: "List my GitHub repositories"
Verify the response shows your actual repositories
Try additional commands like creating issues or searching code

Desktop Extensions vs Manual Configuration

| Feature | Desktop Extensions | Manual Configuration | |---------|-------------------|---------------------| | Setup Time | 1-5 minutes | 15-45 minutes | | Technical Skill | None required | JSON editing, command line | | Updates | Automatic | Manual | | Custom Servers | Limited to marketplace | Unlimited | | Security | Managed, encrypted | Self-managed | | Enterprise Support | Admin policies | Manual deployment | | Offline Use | Depends on extension | Full control |

Method 2: Manual Configuration

Manual configuration gives you complete control over MCP server setup. Use this method for:

Custom or private MCP servers
Servers not available as Extensions
Advanced configuration requirements
Development and testing

Step 1: Locate the Configuration File

Find your Claude Desktop configuration file:

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Full path example: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

macOS:

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

Linux:

~/.config/Claude/claude_desktop_config.json

Pro tip: Open the file in VS Code or another editor with JSON validation. Claude Desktop doesn't show configuration errors, so you'll waste time troubleshooting if your JSON is malformed.

Step 2: Create or Edit the Configuration File

If the file doesn't exist, create it with this structure:

{
  "mcpServers": {}
}

Step 3: Add Your First MCP Server

Let's add the Filesystem server for file access:

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

Configuration breakdown:

| Field | Description | Example | |-------|-------------|---------| | "filesystem" | Unique server name (your choice) | "my-files", "project-docs" | | "command" | Executable to run | "npx", "node", "python" | | "args" | Command-line arguments | Package name, paths, flags | | "env" | Environment variables (optional) | API keys, tokens |

Step 4: Add Multiple Servers

You can configure multiple MCP servers simultaneously:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Step 5: Validate Your Configuration

Before restarting Claude Desktop, validate your JSON:

# Using Python
python3 -m json.tool claude_desktop_config.json

# Using Node.js
node -e "console.log(JSON.parse(require('fs').readFileSync('claude_desktop_config.json', 'utf8')))"

# Online validator: jsonlint.com

Common validation errors:

Trailing commas after the last item in arrays/objects
Missing quotes around strings
Unescaped backslashes in Windows paths (use \\ or /)

Step 6: Restart Claude Desktop

Completely quit Claude Desktop (not just minimize)
- macOS: Cmd+Q or right-click dock icon → Quit
- Windows: Right-click system tray → Exit
Restart Claude Desktop
Look for the MCP indicator (hammer/tools icon) in the chat input
Start a new conversation and test your servers

Windows-Specific Configuration

On Windows, npx is a batch script requiring cmd.exe. Use this format:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c", "npx", "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:/Users/YourName/Documents"
      ]
    }
  }
}

Or use absolute paths to Node.js:

{
  "mcpServers": {
    "filesystem": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": [
        "C:/Users/YourName/AppData/Roaming/npm/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",
        "C:/Users/YourName/Documents"
      ]
    }
  }
}

Having issues? See our comprehensive MCP Server Troubleshooting Guide for solutions to common errors including "spawn npx ENOENT" and "connection closed."

Popular MCP Server Configurations

Here are ready-to-use configurations for the most popular MCP servers:

1. Filesystem Server (File Access)

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

Use cases: Read/write files, browse directories, search file contents

2. GitHub Server (Repository Management)

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

Required token scopes: repo, read:org, read:packages

Use cases: Clone repos, manage issues/PRs, search code, analyze dependencies

Detailed setup: See our GitHub MCP Server Setup Guide for authentication and advanced configuration.

3. PostgreSQL Server (Database Queries)

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

Use cases: Run SQL queries, explore schemas, analyze data

4. SQLite Server (Local Database)

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "--db-path",
        "/path/to/your/database.db"
      ]
    }
  }
}

Use cases: Query local databases, data analysis, prototyping

5. Brave Search Server (Web Search)

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      }
    }
  }
}

Use cases: Web search, research, fact-checking

6. Memory Server (Persistent Knowledge)

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Use cases: Store facts, remember context across conversations

Complete Developer Setup

Here's a comprehensive configuration for software developers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/developer/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://dev:password@localhost:5432/devdb"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Troubleshooting Common Issues

Quick Fixes for Common Problems

| Problem | Quick Fix | |---------|-----------| | Server not appearing | Restart Claude Desktop completely | | "spawn npx ENOENT" (Windows) | Use "command": "cmd", "args": ["/c", "npx", ...] | | Connection closed immediately | Check for console.log() in server (use console.error() instead) | | JSON parse error | Validate JSON at jsonlint.com | | Node.js not found | Use absolute path: /opt/homebrew/bin/node or C:/Program Files/nodejs/node.exe |

Server Not Starting

Symptoms: No MCP indicator in Claude Desktop

Solutions:

Validate JSON syntax with python3 -m json.tool config.json
Use absolute paths for commands and arguments
Test the server command directly in terminal
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/mcp.log
- Windows: %APPDATA%\Claude\logs\mcp.log

Authentication Failures

Symptoms: "401 Unauthorized" or "Invalid token" errors

Solutions:

Regenerate API tokens/keys
Verify required permission scopes
Check token expiration
Use environment variables correctly in "env" block

Deep dive: See our MCP Authentication Troubleshooting Guide for detailed solutions.

Error -32000: Connection Closed

This is the most common MCP error. Main causes:

stdout pollution - Server writes to stdout instead of stderr
Missing dependencies - Required packages not installed
Path issues - Relative paths fail in GUI apps

Solution for stdout pollution:

// Wrong - corrupts MCP protocol
console.log("Debug message");

// Correct - use stderr for logging
console.error("Debug message");

Complete error reference: Our MCP Troubleshooting Guide 2025 covers all error codes including -32000, -32001, and Inspector issues.

Security Best Practices

Protect your MCP server configurations and credentials:

Credential Management

Never commit credentials to version control
Use environment variables for sensitive data:

{
  "mcpServers": {
    "api-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Rotate tokens regularly (monthly for high-security environments)
Use least-privilege permissions when creating API tokens

File System Access

Limit directory access to necessary paths only
Avoid exposing system directories or sensitive folders
Use read-only access when write isn't needed

Network Security

Use HTTPS for all remote MCP server connections
Validate server certificates for production deployments
Implement rate limiting for API-based servers

Enterprise security: See our MCP Security Best Practices Guide for comprehensive security implementation.

Next Steps

Now that you have MCP servers running, explore these resources:

Expand Your Setup

Top 10 MCP Servers 2025 - Find the best servers for your workflow
MCP Server Directory - Browse 1,000+ available MCP servers

Advanced Topics

Custom MCP Server Development - Build your own servers
Advanced MCP Patterns - Professional development practices
MCP Performance Optimization - Speed up your setup

Troubleshooting

MCP Troubleshooting Guide 2025 - Fix common errors
MCP Authentication Guide - Resolve auth issues

Community Resources

Frequently Asked Questions

What is an MCP server?

An MCP (Model Context Protocol) server is a standardized interface that allows Claude to connect to external tools, databases, APIs, and services. MCP servers expose three types of capabilities:

Resources - Data that Claude can read (files, database records, API responses)
Tools - Functions that Claude can execute (search, create files, run queries)
Prompts - Pre-built templates for common tasks

How do I install an MCP server in Claude Desktop?

You can install MCP servers using two methods:

Desktop Extensions (easiest): Go to Settings > Extensions, browse available servers, and click Install.
Manual configuration: Edit the claude_desktop_config.json file and add server configuration in the mcpServers object.

Where is the Claude Desktop config file located?

The configuration file location depends on your operating system:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Why is my MCP server not connecting?

Common causes include:

Invalid JSON syntax - Validate your config file
Wrong file paths - Always use absolute paths
Missing dependencies - Ensure Node.js/Python is installed
Logging to stdout - Use console.error() instead of console.log()

See our troubleshooting guide for detailed solutions.

Can I run multiple MCP servers simultaneously?

Yes! Claude Desktop supports multiple concurrent MCP servers. Add each server to the mcpServers object in your configuration file with a unique name. All servers run independently and Claude can use tools from any of them.

Are MCP servers secure?

MCP servers run locally on your machine with the permissions you grant. Security best practices include:

Using environment variables for credentials
Limiting file system access to necessary directories
Regularly rotating API tokens
Using HTTPS for remote servers

Do I need to restart Claude Desktop after configuration changes?

Yes. After modifying claude_desktop_config.json, you must completely quit Claude Desktop (not just minimize) and restart it for changes to take effect.

What's the difference between Desktop Extensions and manual configuration?

| Aspect | Desktop Extensions | Manual Configuration | |--------|-------------------|---------------------| | Setup | One-click install | Edit JSON files | | Updates | Automatic | Manual | | Custom servers | Marketplace only | Any server | | Security | Managed | Self-managed |

This guide is maintained by the MCP Directory team and updated regularly based on community feedback, MCP specification changes, and new server releases. Last updated: December 2025.