Integrating MCP with Claude Desktop

Claude Desktop is currently the premier client for the Model Context Protocol. It offers a seamless native integration that makes adding servers as easy as editing a text file. This guide will walk you through everything you need to know to connect Claude to your local tools and data.

1. Why Claude Desktop?

While many AI interfaces are web-based, Claude Desktop runs natively on your machine. This is critical for MCP because it allows the AI to:

• Communicate with localhost ports: Access local servers and services running on your machine
• Read local files: Access your project files, documents, and data directly
• Execute local commands: Run scripts and tools installed on your system
• Maintain persistent connections: Keep server connections alive across conversations

These capabilities are blocked by browser security sandboxes in web-based interfaces, making the desktop app essential for MCP functionality.

2. How MCP Works with Claude

Understanding the architecture helps you make the most of MCP:

1. Claude Desktop reads your config file on startup to discover available servers
2. It spawns each server as a subprocess using the command you specify
3. Servers communicate via stdio (standard input/output) using JSON-RPC
4. When you ask a question, Claude decides which tools might help
5. Claude calls the appropriate server and incorporates the results into its response

This architecture means servers run locally on your machine, keeping your data private and enabling fast responses.

3. Locating the Config File

Claude Desktop looks for a specific JSON file to know which servers to run. You can find this file manually, or open it via the Claude menu:

Method 1: Via Claude Menu (Recommended)

1. Open Claude Desktop
2. Click on Claude (macOS) or File (Windows) in the menu bar
3. Select Settings...
4. Click on Developer in the sidebar
5. Click Edit Config

This will open the claude_desktop_config.json file in your default code editor.

Method 2: Manual Location

The config file is located at:

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

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

{
  "mcpServers": {}
}

4. Adding Your First Server

Let's add the FileSystem server, which allows Claude to read your project files. This is one of the most useful servers for developers.

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

Understanding the Configuration

• "filesystem" - A unique name you choose for this server
• "command" - The executable to run (npx, node, python, etc.)
• "args" - Arguments passed to the command
• The paths at the end specify which directories Claude can access

5. Using the Integration

Once you've saved the config file:

1. Restart Claude Desktop completely. Quit the app (Cmd+Q on Mac, or right-click the taskbar icon on Windows) and open it again.
2. Look for the tools indicator. You should see a hammer icon or similar indicator showing tools are available.
3. Try a test query: Ask Claude something like "Can you list the files in my Documents folder?"

If connected correctly, Claude will briefly show a "Using tool..." indicator and then respond with the information.

Example Interactions

Here are some things you can ask Claude once the filesystem server is connected:

• "What files are in my Projects folder?"
• "Read the README.md file in my current project"
• "Summarize the contents of my notes folder"
• "Find all TypeScript files in my project"

6. Managing Multiple Servers

You can add as many servers as you want to the mcpServers object. Claude will automatically decide which tool to use based on your question.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_api_key_here"
      }
    }
  }
}

7. Advanced Configuration

Environment Variables

Many servers require API keys or other configuration. Use the env property:

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

Disabling Servers Temporarily

To disable a server without removing its configuration, you can rename it or comment it out (JSON doesn't support comments, so you'd need to remove it temporarily).

Server-Specific Arguments

Each server has its own arguments. Check the server's documentation for available options. Common patterns include:

• Paths to grant access to
• Database connection strings
• API endpoints
• Feature flags

8. Troubleshooting Connections

If the tools indicator doesn't appear or servers aren't working:

Check JSON Syntax

• No trailing commas after the last item in objects or arrays
• All strings must be in double quotes
• Use a JSON validator to check your file

Verify Prerequisites

• Ensure node and npx are installed and in your system PATH
• Run which npx in terminal to verify
• Try running the npx command manually to see if it works

Check the Logs

Claude Desktop logs MCP activity. Check the logs for errors:

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

# Windows
type %APPDATA%\Claude\Logs\mcp*.log

Common Issues

• Server not found: Check that the package name is correct
• Permission denied: Ensure paths exist and are accessible
• Environment variable not set: Verify API keys are correct
• Port already in use: Another process may be using the same port

For more detailed troubleshooting, see our Debugging MCP Servers guide.