Setting Up MCP in Claude Desktop: Complete Configuration Guide

Prerequisites

Before configuring MCP servers in Claude Desktop, ensure you have:

Claude Desktop

Download from claude.ai/download.

If already installed, check for updates via Claude menu → “Check for Updates...”

Node.js

Required for running npm-based MCP servers.

Verify with node --version. Download from nodejs.org.

Understanding MCP Servers

MCP servers are programs that run on your computer and provide specific capabilities to Claude Desktop through a standardised protocol. Each server exposes tools that Claude can use to perform actions—with your approval.

Filesystem Server Capabilities

Reading file contents and directory structures
Creating new files and directories
Moving and renaming files
Searching for files by name or content

Security Note

All actions require your explicit approval before execution. You maintain full control over what Claude can access and modify.

Installing the Filesystem Server

The installation process involves configuring Claude Desktop to automatically start the Filesystem Server whenever you launch the application.

Step 1: Open Claude Desktop Settings

Click on the Claude menu in your system's menu bar (not the settings within the Claude window) and select “Settings...”

Step 2: Access Developer Settings

In the Settings window, navigate to the “Developer” tab in the left sidebar. Click the “Edit Config” button to open the configuration file.

Configuration File Location

Operating System	Configuration Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

macOS Configuration

Replace the contents of your configuration file with:

JSON

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

Important

Replace username with your actual macOS username. The paths specify which directories the server can access.

Windows Configuration

For Windows, use backslashes and your Windows username:

JSON

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\Users\username\Desktop",
        "C:\Users\username\Downloads"
      ]
    }
  }
}

Windows-Specific: APPDATA Environment Variable

If you encounter ENOENT errors related to ${APPDATA}, add the expanded path to your env key:

JSON

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\Users\username\Desktop"],
      "env": {
        "APPDATA": "C:\Users\username\AppData\Roaming\"
      }
    }
  }
}

Using the Filesystem Server

After saving the configuration and restarting Claude Desktop, you'll see an MCP server indicator in the bottom-right corner of the conversation input box.

Example Prompts

Create a file:

“Can you write a poem and save it to my desktop?”

Search files:

“What work-related files are in my downloads folder?”

Organise files:

“Please organise all images on my desktop into a new folder called 'Images'”

Approval Process

Before executing any file system operation, Claude will request your approval. Review each request carefully before approving. You can always deny a request if you're not comfortable with the proposed action.

Adding Other MCP Servers

You can add multiple MCP servers to Claude Desktop. Here are some examples:

GitHub Server

JSON

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Brave Search Server

JSON

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

Troubleshooting

Server not showing up / hammer icon missing

Restart Claude Desktop completely
Check your claude_desktop_config.json file syntax
Verify file paths are absolute and valid
Try running the MCP server command manually in terminal

ENOENT error with ${APPDATA} in paths (Windows)

Add the expanded value of %APPDATA% to your env key
Ensure npm is installed globally
Run: npm install -g npm

Tool calls failing silently

Check Claude logs for errors
Verify your server builds and runs without errors
Try restarting Claude Desktop

Accessing Logs

Claude Desktop logs are located at:

OS	Logs Path
macOS	~/Library/Logs/Claude
Windows	%APPDATA%\Claude\logs

View logs with this command (macOS/Linux):

BASH

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

Advanced Configuration

Database Server Integration

Connect Claude to your PostgreSQL or SQLite databases for querying and analysis:

PostgreSQL Configurationjson

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

SQLite Configurationjson

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "/Users/username/data/mydb.sqlite"
      ]
    }
  }
}

Puppeteer Web Browser Server

Enable Claude to browse the web, take screenshots, and interact with pages:

JSON

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "env": {
        "PUPPETEER_LAUNCH_OPTIONS": "{\"headless\": true, \"args\": [\"--no-sandbox\"]}"
      }
    }
  }
}

Memory Server for Persistent Context

Give Claude persistent memory across conversations using the Memory server:

JSON

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

Complete Multi-Server Configuration

Here's a comprehensive example combining multiple servers:

JSON

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects",
        "/Users/username/Documents"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/devdb"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSAxxxxxxxxxxxx"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Building a Custom MCP Server

Create your own MCP server to expose custom tools to Claude. This example demonstrates building a weather API server using TypeScript.

Step 1: Project Setup

BASH

# Create project directory# Initialize npm project# Initialize npm project# Initialize npm project# Install dependencies# Create tsconfig.json# Create tsconfig.json# Create tsconfig.json# Create tsconfig.json# Create tsconfig.jsonCreate tsconfig.json
npx tsc --init

Step 2: Create the Server

src/index.tstypescript

// Define the tool input schema// Define the tool input schema// Define the tool input schema// Define the tool input schema// Define the tool input schema// Define the tool input schema// Define the tool input schema// Define the tool input schema// Define the tool input schema// Define the tool input schema// Create the server// Create the server// Create the server// Create the server// Create the server// Create the server// Create the server// Create the server// Create the server// Create the server// Create the server// List available tools// List available tools// List available tools// List available tools// List available tools// List available tools// List available tools// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Handle tool calls// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server//api.openweathermap.org/data/2.5/weather?q=${args.city}&units=${args.units}&appid=${apiKey}`;// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the server// Start the serverthe server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server running on stdio");
}

main().catch(console.error);

Step 3: Configure package.json

JSON

{
  "name": "weather-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "weather-mcp-server": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Step 4: Build and Configure Claude

BASH

# Build the server# Add to Claude Desktop confige Desktop config
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/weather-mcp-server/dist/index.js"],
      "env": {
        "OPENWEATHER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Pro Tip

Use console.error() for logging in MCP servers since stdout is reserved for MCP protocol communication.

Debugging Guide

Testing Servers Manually

Test your MCP server outside Claude Desktop to diagnose issues:

BASH

# Test the filesystem server directly# You should see the server waiting for input# You should see the server waiting for input# Press Ctrl+C to exit# Press Ctrl+C to exitto exit

Using the MCP Inspector

The MCP Inspector is an interactive debugging tool for testing servers:

BASH

# Install and run MCP Inspector# Or for your custom server# Or for your custom server# Or for your custom server# Or for your custom serverour custom server
npx @modelcontextprotocol/inspector node /path/to/your/server/dist/index.js

Common Error Patterns

spawn ENOENT

The command executable was not found.

BASH

# Check if npx is available# On Windows, try using full pathng full path
{
  "command": "C:\\Program Files\\nodejs\\npx.cmd",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\..."]
}

Connection refused / timeout

Server failed to start or crashed immediately.

BASH

# Check MCP logs for errors# Verify Node.js version (18+ required)# Verify Node.js version (18+ required)# Test server startup manually Test server startup manually
npx -y @modelcontextprotocol/server-filesystem /path

JSON parse error in config

Invalid JSON syntax in claude_desktop_config.json.

BASH

# Validate JSON syntax# Common issues:# Common issues:# Common issues:# Common issues:# Common issues:# Common issues:# - Trailing commas# - Unescaped backslashes on Windows# - Missing quotes around valuestes around values

Permission denied errors

Server lacks permission to access specified directories.

BASH

# macOS: Grant Full Disk Access to Claude# System Preferences > Privacy & Security > Full Disk Access > Add Claude# Check directory permissions# Ensure paths are absolute, not relative# Good: /Users/username/Desktop# Good: /Users/username/Desktop# Bad: ~/Desktop or ./Desktopop

Enable Verbose Logging

Add environment variables to increase logging detail:

JSON

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "env": {
        "DEBUG": "mcp:*",
        "NODE_ENV": "development"
      }
    }
  }
}

Security Best Practices

Limit Directory Access

Only grant access to specific directories you need. Avoid granting access to your entire home directory or system paths.

Use Environment Variables

Store sensitive data like API keys in environment variables rather than hardcoding them in configuration files.

Review Each Action

Always review the action Claude proposes before approving. Take time to understand what files will be modified or accessed.

Audit Server Code

Before installing third-party MCP servers, review their source code on GitHub to ensure they don't contain malicious functionality.

Database Security Warning

When connecting database servers, use read-only credentials where possible. Never connect production databases without understanding the implications. Consider using a separate development database for Claude interactions.

Frequently Asked Questions

On macOS, the configuration file is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it's at %APPDATA%\Claude\claude_desktop_config.json. You can also access it via Claude menu > Settings > Developer > Edit Config.

First, restart Claude Desktop completely. Check your claude_desktop_config.json for JSON syntax errors. Verify file paths are absolute and valid. Try running the MCP server command manually in terminal. Check logs at ~/Library/Logs/Claude (macOS) or %APPDATA%\Claude\logs (Windows).

Yes, you can add multiple servers to the mcpServers object in your configuration file. Each server runs independently, and Claude will have access to tools from all configured servers. Simply add additional server entries with unique names.

Yes, Claude Desktop requires explicit approval before executing any MCP tool action. This is a security feature that ensures you maintain full control over what Claude can access and modify on your system.

Add the expanded value of %APPDATA% to your env key in the server configuration. For example: "env": {"APPDATA": "C:\Users\username\AppData\Roaming\"}. Also ensure npm is installed globally with: npm install -g npm.

References & Further Reading

Model Context Protocol - Official Documentation- Complete MCP specification and guides
MCP Quickstart for Users- Getting started guide for Claude Desktop
Official MCP Servers Repository- Reference implementations and pre-built servers
Building MCP Servers- Guide to creating custom MCP servers
MCP Inspector Tool- Interactive debugging tool for MCP servers
Anthropic MCP Announcement- Official announcement and vision for MCP
Download Claude Desktop- Official Claude Desktop application
MCP SDK on npm- TypeScript/JavaScript SDK for building MCP servers

Explore More MCP Servers

The Filesystem Server is just the beginning. Explore the official MCP servers repository for databases, APIs, and more integrations.

Key Takeaways

Prerequisites

Claude Desktop

Node.js

Understanding MCP Servers

Filesystem Server Capabilities

Security Note

Installing the Filesystem Server

Step 1: Open Claude Desktop Settings

Step 2: Access Developer Settings

Configuration File Location

macOS Configuration

Important

Windows Configuration

Windows-Specific: APPDATA Environment Variable

Using the Filesystem Server

Example Prompts

Approval Process

Adding Other MCP Servers

GitHub Server

Brave Search Server

Troubleshooting

Server not showing up / hammer icon missing

ENOENT error with ${APPDATA} in paths (Windows)

Tool calls failing silently

Accessing Logs

Advanced Configuration

Database Server Integration

Puppeteer Web Browser Server

Memory Server for Persistent Context

Complete Multi-Server Configuration

Building a Custom MCP Server

Step 1: Project Setup

Step 2: Create the Server

Step 3: Configure package.json

Step 4: Build and Configure Claude

Pro Tip

Debugging Guide

Testing Servers Manually

Using the MCP Inspector

Common Error Patterns

spawn ENOENT

Connection refused / timeout

JSON parse error in config

Permission denied errors

Enable Verbose Logging

Security Best Practices

Limit Directory Access

Use Environment Variables

Review Each Action

Audit Server Code

Database Security Warning

Frequently Asked Questions

References & Further Reading

Explore More MCP Servers

Related Articles

Model Context Protocol (MCP): Complete Guide

Setting Up MCP in OpenCode

MCP Configuration for Cursor IDE

Ayodele Ajayi