Connect to Local MCP Servers

Local MCP servers extend AI capabilities by providing secure access to local resources. This guide shows how to connect Claude Desktop to local servers using the Filesystem Server as an example.

Prerequisites

Required Software

• Claude Desktop: Download from claude.ai/download
• Node.js: Required for most MCP servers. Verify with node --version

Understanding MCP Servers

MCP servers are programs that expose tools to AI clients through a standardized protocol. Each server provides specific capabilities:

All tool executions require explicit user approval, ensuring full control over AI actions.

Configuration File Location

Connecting the Filesystem Server

Step 1: Open Configuration

In Claude Desktop, navigate to Settings → Developer → Edit Config.

Step 2: Add Server Configuration

Replace the config file content with:

macOS:

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

Windows:

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

Step 3: Restart Claude Desktop

Completely quit and restart Claude Desktop. You’ll see an MCP indicator in the input area when successfully connected.

Usage Examples

With the Filesystem Server connected, try these requests:

• “Create a summary of my Documents folder and save it to Desktop”
• “Find all images on my Desktop and organize them into folders”
• “Read the README.md file in my project directory”

Each action requires your approval before execution.

Troubleshooting

Server Not Appearing

1. Verify JSON syntax: Ensure the config file is valid JSON
2. Use absolute paths: Relative paths won’t work
3. Check logs: ~/Library/Logs/Claude/mcp.log (macOS) or %APPDATA%\Claude\logs (Windows)
4. Test manually: Run npx -y @modelcontextprotocol/server-filesystem <paths> in terminal

Getting Debug Logs

# macOS/Linux
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows PowerShell
Get-Content "%APPDATA%\Claude\logs\mcp*.log" -Wait

Tool Call Failures

If tools fail silently:

1. Check server logs for errors
2. Verify the server runs independently
3. Restart Claude Desktop completely

Advanced Configuration

Multiple Servers

You can connect multiple servers simultaneously:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "/path/to/repo"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    }
  }
}

Python Servers

For Python-based MCP servers:

{
  "mcpServers": {
    "python-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/server",
        "run",
        "server.py"
      ]
    }
  }
}

Environment Variables

Pass environment variables to servers:

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["-y", "@your-org/server"],
      "env": {
        "API_KEY": "your-key",
        "API_ENDPOINT": "https://api.example.com"
      }
    }
  }
}

Security Best Practices

1. Principle of Least Privilege: Only grant access to necessary directories
2. Review Permissions: Regularly audit your server configurations
3. Use Absolute Paths: Prevents unintended directory access
4. Monitor Logs: Keep an eye on server activity

Available Servers

Explore official and community servers at github.com/modelcontextprotocol/servers.

Popular options include:

• Filesystem: Local file and directory operations
• Git: Repository operations and history
• GitHub: GitHub integration and PR management
• Postgres: Database queries and management
• Brave Search: Web search capabilities
• Puppeteer: Web automation and scraping

Next Steps

• Build your own server
• Connect to remote servers
• Explore the MCP specification