Skip to main content
← Back to Learn
beginner10 min read

Connect Claude Desktop to Your MCP Server

Claude Desktop has first-class MCP support. This guide walks you through the complete setup: editing the config file, adding your server, verifying the connection, and fixing the most common issues.

Requirements

  • Claude Desktop installed (desktop.claude.ai)
  • A Claude Pro or Teams subscription
  • An MCP server to connect (local or remote)

Don't have an MCP server yet? Start with one of these tutorials:

Step 1 — Find the Config File

Claude Desktop reads MCP server configuration from a JSON file calledclaude_desktop_config.json. Its location depends on your OS:

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

Open Finder → Go → Go to Folder → paste path above

Windows
%APPDATA%\Claude\claude_desktop_config.json

Press Win + R, type %APPDATA%\Claude, press Enter

You can also open it directly from Claude Desktop:

  1. Open Claude Desktop
  2. Click the menu: Claude (macOS) or hamburger icon
  3. Select Settings...
  4. Go to the Developer tab
  5. Click Edit Config

First time? The file may not exist yet. Create it — Claude Desktop will pick it up automatically on the next launch.

Step 2 — Edit the Config File

The config file is JSON with a single top-level key mcpServers. Each key inside is a server name (you choose it), and the value describes how to start it.

claude_desktop_config.json — minimal example
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"]
    }
  }
}

Complete reference

FieldRequiredDescription
commandYesExecutable to run (node, python, uvx, npx, etc.)
argsNoArray of command-line arguments
envNoObject with environment variables (API keys, etc.)
disabledNoSet to true to temporarily disable a server

Real-world examples

Official filesystem server (npx)

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

Python server (via uv)

{
  "mcpServers": {
    "my-python-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/yourname/projects/my-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

Server with API key (env variables)

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

Multiple servers

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "my-custom-server": {
      "command": "python",
      "args": ["/Users/yourname/projects/my-server/server.py"]
    }
  }
}

Step 3 — Restart Claude Desktop and Verify

1

Fully quit Claude Desktop

On macOS: right-click the Dock icon → Quit (just closing the window is not enough). On Windows: right-click the tray icon → Exit.

2

Launch Claude Desktop

Claude will read the config and start all enabled MCP servers in the background.

3

Look for the hammer icon

In a new chat, you should see a hammer (🔨) icon near the input box. Clicking it shows all available MCP tools. If you see it, MCP is connected.

4

Test a tool

Ask Claude to use one of your tools. For example, with the filesystem server: "What files are in my Downloads folder?" Claude will ask for permission before executing.

Troubleshooting

First place to look: the MCP log files. Claude Desktop writes one log per server.

Log file locations
# macOS
~/Library/Logs/Claude/mcp-server-<server-name>.log
~/Library/Logs/Claude/mcp.log          # general MCP log

# Windows
%APPDATA%Claudelogsmcp-server-<server-name>.log
No hammer icon appears

All configured servers failed to start, or the config file has a JSON syntax error.

  • Validate JSON: python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
  • Check the mcp.log for startup errors
Server starts but tools are missing

The server started but returned no tools. This can happen if:

  • Your server code has an error (check the server-specific log)
  • The server responded to the tools/list request with an empty list
Command not found

Claude Desktop runs with a minimal PATH. If you see "command not found" for node, python, etc.:

  • Use the full absolute path to the binary, e.g. /usr/local/bin/node
  • Find the path with: which node or which python3
Server crashes immediately

Try running the command manually in your terminal — you'll see the error directly:

node /path/to/your/server.js

The server should start and wait for input (it's MCP stdio — it blocks on stdin).

Changes not taking effect

You must fully quit Claude Desktop and restart it after any config change. Closing and reopening the window does not restart MCP servers.

Security notes

  • Claude always asks permission before executing an MCP tool. You'll see a dialog for each tool call — you can approve or deny it.
  • API keys in env are stored in a plain-text JSON file. Do not commit this file to git. Consider using a secrets manager for production setups.
  • Trust your servers. MCP servers run as your user with your OS permissions. Only connect servers from sources you trust.

Build your own MCP server

Now that Claude Desktop is connected, create a custom server to give Claude access to your own data and tools.

Python MCP Server →TypeScript MCP ServerMCP vs Function Calling