The claude_desktop_config.json file tells Claude Desktop which MCP servers to start and what settings each server needs. If you want to connect tools like GitHub, filesystem access, databases, browsers, or local scripts through MCP, this local JSON file is where those server definitions go.
This independent guide explains what the file does, where to create it, how the JSON is structured, and how to avoid common mistakes. It is not affiliated with or endorsed by Anthropic or Claude.
If you want a faster starting point, use the Claude Desktop MCP Config Generator, then review the output before adding it to your own local Claude Desktop setup. The generator runs in the browser and uses placeholder environment variable names instead of real secrets.
Key takeaways
- Create the file locally in the Claude Desktop config folder for your operating system.
- Use a top-level mcpServers object, then add one named MCP server entry at a time.
- Keep public examples safe by using placeholders such as ${GITHUB_TOKEN} instead of real API keys.
What is claude_desktop_config.json?
claude_desktop_config.json is a local configuration file used by Claude Desktop to define MCP servers. Each server entry tells Claude Desktop which command to run, which arguments to pass, and which environment variables the server needs.
A basic file contains a top-level mcpServers object. Each key inside that object is the local name of one MCP server. Choose names that are short, descriptive, and unique.
- Server name
- Command
- Command arguments
- Environment variables
- Optional working directory
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}Where to create the file
The config file is created on your own computer, not inside a website. If the file does not exist yet, create it manually with a plain text editor and save it with the exact filename claude_desktop_config.json.
Common locations are the Claude application support folder on macOS and the Claude app data folder on Windows. Paths can vary by installation, so verify against your local Claude Desktop version if the folder is missing.
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Use plain text, not rich text
- Restart Claude Desktop after saving
Basic file structure
The smallest valid config has an mcpServers object. Add one server entry inside it, then validate the JSON before adding more servers.
The command field is the executable Claude Desktop should run. The args field must be an array, not a single string. Use cwd only when a server explicitly needs a working directory.
- command: executable name or path
- args: ordered command-line arguments
- env: optional key-value variables
- cwd: optional working directory
{
"mcpServers": {
"example-server": {
"command": "npx",
"args": ["-y", "example-mcp-server"]
}
}
}Add environment variables safely
Some MCP servers require tokens, API keys, database URLs, or local settings. In shared examples, generated previews, screenshots, or documentation, use placeholder values instead of real secrets.
For your private local file, follow the server documentation for how it expects secrets. A static browser tool can generate a template, but it should not upload, store, or log your credentials.
- Use ${GITHUB_TOKEN} in public examples
- Use ${DATABASE_URL} for database placeholders
- Do not commit real claude_desktop_config.json secrets
- Separate dev and production credentials
Example config with multiple MCP servers
You can define more than one MCP server in the same file. Keep each server entry separate so failures are easier to debug.
Start with one read-only server, restart Claude Desktop, and confirm it works before adding filesystem, browser, database, or write-capable tools.
- Add one server at a time
- Prefer read-only scopes first
- Keep names descriptive
- Review permissions before enabling write actions
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/your-name/Documents"]
}
}
}Step-by-step setup flow
Choose the MCP servers you want to use, find the documented command and arguments for each server, then create or edit the Claude Desktop config file. Validate the JSON before saving and restart Claude Desktop after every change.
If you use a browser-based generator, copy the generated JSON, review it, replace placeholders with your local environment setup where appropriate, and save it manually on your own machine.
- Choose servers
- Collect command, args, and env names
- Create the file
- Validate JSON
- Restart Claude Desktop
- Test one server before adding more
Common mistakes to check
Most Claude Desktop MCP config problems are simple JSON, path, or dependency issues. Check the basics before replacing the whole file.
JSON does not allow comments, trailing commas, smart quotes, or unquoted keys. File paths must exist on your machine, and runtime dependencies such as Node.js must be installed if the command uses npx.
- Trailing commas
- Wrong filename
- Wrong config folder
- Smart quotes
- Missing Node.js
- Env names that do not match the server docs
- Real secrets in shared screenshots
Implementation checklist
- The filename is exactly claude_desktop_config.json
- The file is in the correct Claude Desktop config folder
- The JSON has a top-level mcpServers object
- Each server has a unique local name
- Each server has the correct command
- args is an array, not a plain string
- Public examples use placeholders instead of real secrets
- The JSON has no trailing commas
- Claude Desktop was restarted after saving changes
FAQ
What does claude_desktop_config.json do?
It defines which MCP servers Claude Desktop should run locally. Each server entry tells Claude Desktop the command, arguments, and optional environment variables needed to start that MCP server.
Do I need to create claude_desktop_config.json manually?
If the file does not already exist, yes. You can create it with any plain text editor. A browser-based generator can help produce the JSON, but the file still needs to be saved locally in the correct Claude Desktop config folder.
Can I use real API keys in the config file?
For your private local file, some MCP servers may require real tokens or keys. For public examples, generated previews, screenshots, or documentation, never use real secrets. Use placeholders like ${GITHUB_TOKEN} or ${API_KEY}.
Why is my MCP server not showing up?
Common causes include invalid JSON, the wrong file location, a misspelled command, missing dependencies, or forgetting to restart Claude Desktop after editing the file. Start with one server, validate the JSON, then add more.
Can a static website create the config file automatically?
A static, browser-only site can generate JSON for you to copy or download, but it should not directly modify files on your computer. You still need to review the output and place the file in the correct local Claude Desktop config folder.