How to Set Up Your First MCP Server with Claude Desktop: A Complete Guide

Setting up your first Model Context Protocol (MCP) server with Claude Desktop might seem daunting, but I'll walk you through every step. After helping dozens of developers get started with MCP, I've refined this process to be as straightforward as possible.

By the end of this guide, you'll have a fully functional MCP server connected to Claude Desktop, ready to extend Claude's capabilities with external tools and data sources.

What You'll Build

In this tutorial, you'll:

Install and configure Claude Desktop
Set up your first MCP server (we'll use the Filesystem MCP as an example)
Connect the MCP server to Claude Desktop
Test the connection and verify it's working
Troubleshoot common issues

Time required: 15-30 minutes
Difficulty: Beginner-friendly

Prerequisites and Requirements

Before we begin, make sure you have:

Required Software

Claude Desktop: Download from claude.ai/download (external resource)
Node.js 18+: Check your version with node --version
npm or yarn: Package manager (comes with Node.js)
Text editor: VS Code, Sublime, or any editor you prefer

Required Knowledge

Basic command line usage
Understanding of JSON configuration files
Familiarity with file paths on your operating system

System Requirements

macOS: 10.15 (Catalina) or later
Windows: Windows 10 or later
Linux: Most modern distributions
RAM: 4GB minimum, 8GB recommended
Disk Space: 500MB for Claude Desktop and MCP servers

Step 1: Install Claude Desktop

If you haven't already installed Claude Desktop:

macOS

Download Claude Desktop from the official website
Open the downloaded .dmg file
Drag Claude to your Applications folder
Launch Claude from Applications

Windows

Download the Claude Desktop installer
Run the .exe file
Follow the installation wizard
Launch Claude from the Start menu

Linux

# Download the AppImage
wget https://claude.ai/download/linux/claude-desktop.AppImage

# Make it executable
chmod +x claude-desktop.AppImage

# Run Claude Desktop
./claude-desktop.AppImage

Verify Installation: Open Claude Desktop and sign in with your Anthropic account. You should see the main chat interface.

Step 2: Understanding MCP Configuration

Claude Desktop uses a configuration file to know which MCP servers to connect to. The location of this file varies by operating system:

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

This JSON file tells Claude Desktop:

Which MCP servers to start
How to start them (command and arguments)
Environment variables to pass

Step 3: Choose Your First MCP Server

For this tutorial, we'll use the Filesystem MCP Server because it's:

Easy to set up
Immediately useful (gives Claude access to local files)
Great for learning MCP concepts
Officially maintained by Anthropic

What it does: Allows Claude to read, write, and search files in specified directories on your computer.

Step 4: Install the Filesystem MCP Server

Open your terminal and install the server globally:

npm install -g @modelcontextprotocol/server-filesystem

Verify installation:

which mcp-server-filesystem
# Should output the path to the installed server

Alternative: Install Locally

If you prefer not to install globally:

# Create a directory for MCP servers
mkdir -p ~/mcp-servers
cd ~/mcp-servers

# Install locally
npm install @modelcontextprotocol/server-filesystem

Step 5: Configure Claude Desktop

Now we'll tell Claude Desktop about your MCP server.

Create the Configuration File

If the config file doesn't exist, create it:

macOS/Linux:

mkdir -p ~/Library/Application Support/Claude
touch ~/Library/Application Support/Claude/claude_desktop_config.json

Windows (PowerShell):

New-Item -Path "$env:APPDATA\Claude" -ItemType Directory -Force
New-Item -Path "$env:APPDATA\Claude\claude_desktop_config.json" -ItemType File

Add Your MCP Server Configuration

Open the config file in your text editor and add:

For Global Installation:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["/Users/yourname/Documents"],
      "env": {}
    }
  }
}

For Local Installation:

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/Users/yourname/mcp-servers/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",
        "/Users/yourname/Documents"
      ],
      "env": {}
    }
  }
}

Important: Replace /Users/yourname/Documents with the actual path you want to give Claude access to.

Configuration Breakdown

Let's understand each part:

mcpServers: Object containing all your MCP server configurations
"filesystem": A unique name for this server (you choose this)
command: The executable to run
args: Arguments passed to the command (including the directory path)
env: Environment variables (empty for now)

Security Considerations

⚠️ Important: Only give Claude access to directories you're comfortable with it reading and modifying. Start with a test directory:

# Create a safe test directory
mkdir -p ~/claude-test
echo "Hello from MCP!" > ~/claude-test/test.txt

Then use ~/claude-test in your configuration.

Step 6: Restart Claude Desktop

For the configuration to take effect:

Quit Claude Desktop completely (not just close the window)
- macOS: Right-click Claude in the Dock → Quit
- Windows: Right-click system tray icon → Exit
- Linux: Close all windows and kill the process if needed
Relaunch Claude Desktop
Check for MCP indicator: Look for a small icon or indicator showing MCP servers are connected (usually in the bottom-left or settings area)

Step 7: Test Your MCP Connection

Now let's verify everything is working!

Test 1: Basic File Reading

In Claude Desktop, try this prompt:

Can you read the test.txt file in my claude-test directory?

Expected result: Claude should read and display the contents of the file.

Test 2: List Directory Contents

What files are in my claude-test directory?

Expected result: Claude should list all files in the directory.

Test 3: Create a New File

Create a file called "mcp-works.txt" with the content "MCP is working!" in my claude-test directory.

Expected result: Claude should create the file, and you can verify it exists in your file system.

Test 4: Search Files

Search for the word "MCP" in all files in my claude-test directory.

Expected result: Claude should find and report all occurrences.

Troubleshooting Common Issues

Issue 1: MCP Server Not Connecting

Symptoms: Claude doesn't respond to file-related requests or says it can't access files.

Solutions:

Check the config file syntax (use a JSON validator)
Verify the file path in your config is correct
Ensure the MCP server is installed correctly
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/
- Windows: %APPDATA%\Claude\logs\
- Linux: ~/.config/Claude/logs/

Issue 2: Permission Denied Errors

Symptoms: Claude says it can't access the directory.

Solutions:

Check directory permissions: ls -la ~/claude-test
Ensure the directory exists
Try a different directory with full permissions
On macOS, grant Claude Full Disk Access in System Preferences → Security & Privacy

Issue 3: Command Not Found

Symptoms: Error about mcp-server-filesystem not being found.

Solutions:

Verify installation: npm list -g @modelcontextprotocol/server-filesystem
Use the full path to the server in your config
Try the local installation method instead

Issue 4: Configuration Not Loading

Symptoms: Changes to config file don't take effect.

Solutions:

Verify you're editing the correct config file location
Ensure the JSON is valid (no trailing commas, proper quotes)
Completely quit and restart Claude Desktop (not just close window)
Check for typos in the file path

Debugging Tips

Enable verbose logging by adding to your config:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["/Users/yourname/claude-test"],
      "env": {
        "DEBUG": "*"
      }
    }
  }
}

Then check the logs for detailed error messages.

Advanced Configuration

Multiple Directories

Give Claude access to multiple directories:

{
  "mcpServers": {
    "filesystem-docs": {
      "command": "mcp-server-filesystem",
      "args": ["/Users/yourname/Documents"]
    },
    "filesystem-projects": {
      "command": "mcp-server-filesystem",
      "args": ["/Users/yourname/Projects"]
    }
  }
}

Read-Only Access

Some MCP servers support read-only mode. Check the server's documentation for available options.

Environment Variables

Pass API keys or other configuration:

{
  "mcpServers": {
    "custom-server": {
      "command": "custom-mcp-server",
      "args": [],
      "env": {
        "API_KEY": "your-api-key-here",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Adding More MCP Servers

Now that you have one working, adding more is easy! Popular options:

GitHub MCP Server

Access your GitHub repositories:

npm install -g @modelcontextprotocol/server-github

PostgreSQL MCP Server

Connect to databases:

npm install -g @modelcontextprotocol/server-postgres

Slack MCP Server

Integrate with Slack:

npm install -g @modelcontextprotocol/server-slack

Add each to your claude_desktop_config.json following the same pattern.

Best Practices

Start Small: Begin with one MCP server and one directory
Test Thoroughly: Verify each server works before adding another
Use Test Directories: Don't give access to sensitive files initially
Keep Config Organized: Comment your JSON (using a JSON5 parser if needed)
Monitor Performance: Too many MCP servers can slow down Claude Desktop
Update Regularly: Keep your MCP servers updated with npm update -g

Real-World Use Cases

Here's what you can do with your new setup:

Code Review Assistant

Review all Python files in my project directory and suggest improvements.

Documentation Generator

Read all the .js files in my src directory and create API documentation.

Log Analysis

Search my logs directory for any error messages from the last week.

Batch File Processing

Find all .txt files in my notes directory and create a summary of each.

Next Steps

Now that you have MCP working:

Explore More Servers: Browse our MCP server directory to find servers for your needs
Build Custom Servers: Learn to create your own MCP servers with our development guide
Join the Community: Share your setup and learn from others
Optimize Your Workflow: Discover advanced MCP patterns and techniques

Common Questions

Q: Can I use multiple MCP servers at once?
A: Yes! Claude can use all configured MCP servers simultaneously.

Q: Does this work with Claude API or just Claude Desktop?
A: This guide is for Claude Desktop. The Claude API has different integration methods.

Q: Are MCP servers secure?
A: MCP servers run locally on your machine. Only give access to directories you trust Claude with.

Q: Can I disable an MCP server temporarily?
A: Yes, just remove it from the config file or comment it out, then restart Claude Desktop.

Q: How much does this cost?
A: MCP servers are free and open source. You only pay for your Claude subscription.

Conclusion

Congratulations! You've successfully set up your first MCP server with Claude Desktop. You now have a powerful foundation for extending Claude's capabilities with external tools and data sources.

The Filesystem MCP server is just the beginning. With 177+ MCP servers available in our directory, you can connect Claude to databases, APIs, cloud services, and much more.

What's your next MCP integration? Explore our directory to find the perfect server for your workflow.

Last updated: March 2025. This guide is maintained by the MCPList.ai community and reflects current best practices for MCP server setup.