How to Set Up MCP Servers in Claude Desktop (Complete Guide)

Claude Desktop is a capable tool on its own, but it is limited to what you type or paste into the chat window. It cannot read your files, check your databases, or pull context from the tools you use every day.

MCP (Model Context Protocol) changes that. By configuring MCP servers, you give Claude Desktop direct access to your filesystem, GitHub repos, Slack workspace, databases, and more -- all running locally on your machine, under your control.

This guide walks you through the entire setup process, starting from scratch. If you have never edited a JSON config file before, the beginner section covers every step. If you already have one server running and want to add more, skip ahead to the intermediate section. The advanced section covers troubleshooting for when things go wrong.

What Is MCP? (And Why It Matters)

The Model Context Protocol (MCP) is an open standard developed by Anthropic that lets Claude connect to external tools, data sources, and services. Think of it as the equivalent of browser extensions, but for Claude Desktop.

MCP servers are small programs that run on your computer. When Claude Desktop starts, it launches these servers and communicates with them through a standard protocol. Each server exposes "tools" that Claude can use -- like read_file, create_github_issue, or search_slack. Before Claude executes any tool, it asks for your approval.

With MCP servers configured, Claude can:

• Read and write files in directories you specify
• Search the web and fetch live data
• Interact with GitHub -- read code, create issues, open pull requests
• Query databases like PostgreSQL and SQLite
• Connect to work tools like Slack, Notion, and Google Drive
• Access domain-specific context -- for example, GTM knowledge via Octave

The setup involves editing a single JSON config file and restarting Claude Desktop. Let's start with what you need installed.

Prerequisites

If you already have Claude Desktop installed, check for updates first: click the Claude menu in your system menu bar and select "Check for Updates."

Finding the Config File

MCP servers are defined in a file called claude_desktop_config.json. The location depends on your operating system:

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

# Windows
%APPDATA%\Claude\claude_desktop_config.json

If you prefer the terminal:

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

notepad %APPDATA%\Claude\claude_desktop_config.json

Your First MCP Server: Filesystem Access

The filesystem server is the most common starting point. It gives Claude the ability to read and write files in directories you choose -- useful for working with local projects, documents, or code.

Step 1: Add the Config

If the config file is empty or does not exist yet, paste this entire block. If it already has content, add the mcpServers section:

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

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

Step 2: Restart Claude Desktop

After saving the config file, completely quit Claude Desktop and reopen it. Closing the window is not enough -- the app needs to fully restart to load the new config.

• macOS: Cmd+Q to quit, then reopen from Applications
• Windows: Right-click the tray icon, click Exit, then reopen

Step 3: Verify It Works

Open a new chat in Claude Desktop. Look for the MCP server indicator in the bottom-right of the message input area. Click it to see a list of available tools -- you should see filesystem tools like read_file, write_file, and list_directory.

Try asking Claude: "List the files in my Documents folder." It should now be able to browse the directories you configured.

How the Config File Works

Now that you have one server running, it helps to understand the structure behind it. Every MCP server entry in your config follows the same pattern:

{
  "mcpServers": {
    "server-name": {           // A name you choose (must be unique)
      "command": "npx",          // How to run it -- usually "npx" or "node"
      "args": [                   // Arguments passed to the command
        "-y",                     // Auto-confirm npx package install
        "@package/server-name",   // The npm package to run
        "/path/to/data"           // Optional: paths or flags
      ],
      "env": {                    // Optional: environment variables
        "API_KEY": "your-key"     // Passed securely to the server process
      }
    }
  }
}

The command and args fields tell Claude Desktop how to start the server process. The env field passes environment variables -- this is where API keys and tokens go.

To run multiple servers, add more entries to the mcpServers object. Each server runs independently, and all their tools are available in every conversation:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA_xxxxxxxxxxxx"
      }
    }
  }
}

Save the file, restart Claude Desktop, and all three servers will be available.

Popular MCP Servers (Copy-Paste Configs)

Below are ready-to-use configurations for the most commonly used MCP servers. Copy the relevant block, add it to your mcpServers object, and fill in your credentials.

GitHub

Read code, create issues, open pull requests, and manage repositories from Claude.

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

To get a GitHub token: Go to GitHub Settings > Developer settings > Personal access tokens, generate a new token (classic), and select the repo scope for full repository access.

Brave Search

Give Claude the ability to search the web and retrieve current information.

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

Get a Brave Search API key at brave.com/search/api. The free tier includes 2,000 queries per month.

Slack

Read messages, search channels, and post to Slack directly from Claude.

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

PostgreSQL

Query your PostgreSQL databases from Claude. Useful for exploring data, running reports, or debugging.

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

Connecting Octave: GTM Context in Claude Desktop

The servers above connect Claude to developer tools -- code, databases, search. But MCP is not limited to engineering workflows. It can also bring domain-specific context into Claude, which is where things get more interesting for GTM teams.

Octave is a GTM context engine for B2B SaaS companies. It centralizes the knowledge that typically lives in scattered docs, Notion pages, and people's heads: ICP definitions, persona pain points, competitive positioning, value propositions, proof points, and reference customers. Octave exposes this knowledge through an MCP server, so Claude Desktop can query it directly.

The practical difference: instead of pasting your positioning doc into every Claude conversation, or rewriting the same context in every prompt, Claude pulls the relevant GTM knowledge automatically. Ask it to "write an email to a VP of Sales at a fintech company" and it can look up your VP Sales persona, pull value props relevant to fintech, and reference a case study you actually have -- without you doing the lookup.

Setting It Up

Octave's MCP server uses a remote connection, so the config looks slightly different from the local servers above. It uses the mcp-remote package to connect to Octave's hosted MCP endpoint:

"octave": {
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://mcp.octavehq.com/mcp?ctx=YOUR_CONTEXT"
  ]
}

To get your context value:

1. Log in to your Octave dashboard
2. Navigate to the "Connect Via MCP" option
3. Copy the context string provided
4. Replace YOUR_CONTEXT in the config above with that value

Save the file, restart Claude Desktop, and Octave's tools will appear alongside your other MCP servers.

Desktop Extensions: The Simpler Path

Everything above involves manually editing a JSON config file. That works, and it is the most flexible approach. But since mid-2025, Claude Desktop has offered a simpler alternative: Desktop Extensions.

Desktop Extensions are MCP servers packaged as .mcpb (MCP Bundle) files -- essentially zip archives containing the server code and a manifest. Instead of editing JSON and installing Node.js, you download a .mcpb file, double-click it, and click "Install." Claude Desktop includes a built-in Node.js runtime, so there are no external dependencies to manage.

To install extensions from the directory:

1. Open Claude Desktop
2. Go to Settings > Extensions
3. Click "Browse extensions" to see the Anthropic-reviewed directory
4. Click "Install" on any extension you want
5. Configure any required settings (API keys, directory paths) when prompted

You can also install custom .mcpb files that are not in the directory. Go to Settings > Extensions > Advanced settings, find the Extension Developer section, and click "Install Extension" to select a file.

Troubleshooting MCP Servers

MCP server setup usually works on the first try, but when it does not, the errors can be cryptic. Here is how to diagnose the most common problems.

Servers Not Appearing

If you do not see the MCP server indicator (or the old hammer icon) after restarting Claude Desktop:

1. Did you fully restart? Closing the window is not enough. On macOS, press Cmd+Q. On Windows, right-click the tray icon and click Exit. Then reopen the app.
2. Is your JSON valid? A single missing comma or bracket breaks the entire config. Validate it by running:

   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

   If there is a syntax error, Python will tell you exactly which line.
3. Is Node.js installed? Run node --version and npx --version in your terminal. Both should return version numbers.
4. Try running the server manually. Copy the command and args from your config and run them directly in the terminal:

   npx -y @modelcontextprotocol/server-filesystem /Users/yourname/Documents

   If there is a problem with the package or your paths, you will see the error directly.

Viewing MCP Server Logs

Claude Desktop writes MCP-related logs to your system's log directory. These are the first place to look when a server starts but then fails:

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

# Windows (PowerShell)
type "$env:APPDATA\Claude\logs\mcp*.log"

The file mcp.log contains general connection information. Files named mcp-server-SERVERNAME.log contain error output from each specific server.

Common Error Messages

• "spawn npx ENOENT" -- Node.js is not installed or npx is not in your system PATH. Install Node.js from nodejs.org. On Windows, you may also need to install npm globally with npm install -g npm.
• "EACCES permission denied" -- Claude cannot access a directory you specified. Check permissions with ls -la /path/to/directory and make sure the paths are absolute, not relative.
• "Invalid JSON" or parse errors -- Syntax error in your config file. Check for missing commas between server entries, unmatched brackets, or stray characters.
• "GITHUB_PERSONAL_ACCESS_TOKEN is not set" -- The environment variable name is misspelled or missing from the env object. Double-check the exact key names required by each server.

Windows-Specific Issues

On some Windows configurations, npx does not resolve correctly when called directly. If you see ENOENT errors on Windows, try wrapping the command with cmd:

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

You may also need to add the expanded APPDATA path to the env block if errors reference ${APPDATA} in log output:

"env": {
  "APPDATA": "C:\\Users\\yourname\\AppData\\Roaming",
  "BRAVE_API_KEY": "BSA_your_key_here"
}

Frequently Asked Questions

Where is claude_desktop_config.json located?

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Or open it from Claude Desktop: Claude menu > Settings > Developer > Edit Config.

What is MCP in Claude Desktop?

MCP (Model Context Protocol) is an open standard created by Anthropic that lets Claude Desktop connect to external tools and data sources through locally running server processes. Each server exposes tools that Claude can invoke with your approval.

How do I add an MCP server to Claude Desktop?

Add a new entry to the mcpServers object in claude_desktop_config.json with the server name, command, args, and optional env variables. Save the file and fully restart Claude Desktop.

Why are my MCP servers not showing up?

The most common cause is not fully restarting Claude Desktop -- you need to quit the app (Cmd+Q on Mac, Exit from tray on Windows), not just close the window. Also check for JSON syntax errors and verify Node.js is installed.

Can I run multiple MCP servers at once?

Yes. Add as many entries to the mcpServers object as you need. Each runs as an independent process, and all their tools are available in your conversations.

How do I update an MCP server?

If you are using npx with the -y flag, it pulls the latest version of the package each time Claude Desktop starts. For Desktop Extensions, updates are handled automatically.

Is MCP secure?

MCP servers run locally on your machine with the permissions you grant. Only configure servers from trusted sources. Use the env object for API keys (not args), and only give file access to directories you want Claude to read or modify. Claude always asks for approval before executing any tool action.

Should I use Desktop Extensions or manual JSON config?

Desktop Extensions are easier to install and manage -- use them when the server you want is available in the directory. Use manual JSON config for servers not in the directory, private or custom servers, or when you need fine-grained control over configuration options.