How to connect MCP servers to Claude Desktop

Claude Desktop stores its configuration in a JSON file at a platform-specific location. On macOS, open Finder and navigate to ~/Library/Application Support/Claude/. On Windows, navigate to %APPDATA%\Claude\. If the file does not exist, create it. You can also open it quickly from Claude Desktop's settings menu.

1# macOS — open the config file in your default editor
2open ~/Library/Application Support/Claude/claude_desktop_config.json
3
4# macOS — if the file does not exist, create it
5mkdir -p ~/Library/Application\ Support/Claude
6touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
7
8# Windows (PowerShell)
9notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Add a mcpServers object to the config file. Each server entry has a unique name (the key) and an object with command (the executable to run) and args (command-line arguments). This example adds the official Filesystem MCP server, which gives Claude access to read and write files in a specified directory.

1{
2  "mcpServers": {
3    "filesystem": {
4      "command": "npx",
5      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
6    }
7  }
8}

Many MCP servers need API keys or connection strings. Use the env field to pass environment variables securely. These are injected into the server's process environment when Claude Desktop launches it. Never put API keys directly in the args array.

1{
2  "mcpServers": {
3    "filesystem": {
4      "command": "npx",
5      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
6    },
7    "github": {
8      "command": "docker",
9      "args": ["run", "-i", "--rm",
10        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
11        "ghcr.io/github/github-mcp-server"],
12      "env": {
13        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
14      }
15    },
16    "brave-search": {
17      "command": "npx",
18      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
19      "env": {
20        "BRAVE_API_KEY": "your-brave-api-key"
21      }
22    }
23  }
24}

If you built a custom MCP server (TypeScript or Python), add it to the config by specifying the execution command. For TypeScript servers, use npx tsx to run the source directly or node to run compiled JavaScript. For Python servers, use python or uv run.

1{
2  "mcpServers": {
3    "my-custom-server": {
4      "command": "npx",
5      "args": ["-y", "tsx", "/Users/you/projects/my-server/src/index.ts"]
6    },
7    "python-server": {
8      "command": "uv",
9      "args": ["run", "--directory", "/Users/you/projects/py-server", "server.py"]
10    }
11  }
12}

For remote MCP servers running on another machine or cloud, use the url field instead of command/args. Claude Desktop connects to the server over Streamable HTTP. This is useful for shared team servers or cloud-deployed MCP services.

1{
2  "mcpServers": {
3    "remote-api": {
4      "url": "https://mcp.your-company.com/api"
5    }
6  }
7}

After saving the config file, completely quit Claude Desktop (Cmd+Q on macOS, not just close the window) and reopen it. Look for the hammer icon in the chat input area — this indicates MCP tools are available. Click it to see the list of available tools from all connected servers. If you do not see the hammer icon, the servers may have failed to connect.

Ask Claude a question that requires an MCP tool. For example, with the filesystem server connected, ask 'What files are in my Documents folder?' Claude will request permission to use the tool, show you the tool call, and display the result. You can approve individual tool calls or allow all calls from a specific server.