Lesson 11 - Step 2 of 5

Configuration File

Understand the claude_desktop_config.json file format and location.

The Configuration File

Claude Desktop uses a JSON configuration file to know which MCP servers to connect to. This file is called claude_desktop_config.json and lives in a platform-specific location.

File Location

Find or create the configuration file at:

bash

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

# Windows
%APPDATA%\Claude\claude_desktop_config.json

# Linux
~/.config/claude/claude_desktop_config.json

Quick Access on macOS

Open Terminal and run: open ~/Library/Application\ Support/Claude/ to open the folder in Finder. You may need to create the file if it doesn't exist.

Basic File Structure

The configuration file has a simple structure with an mcpServers object that maps server names to their configurations:

json

{
  "mcpServers": {
    "server-name": {
      "command": "path/to/executable",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Configuration Options

Each server configuration supports the following fields:

Field	Required	Description
`command`	Yes	The executable to run (e.g., "python", "node", "/usr/bin/my-server")
`args`	No	Array of command-line arguments
`env`	No	Object of environment variables to set

Example: Python Server

Here's how to configure a Python-based MCP server:

json

{
  "mcpServers": {
    "mcp-tools": {
      "command": "python3",
      "args": ["/Users/you/projects/mcp-server/stdio_example.py"]
    }
  }
}

Example: Node.js Server

For a Node.js-based server:

json

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/Users/you/projects/mcp-filesystem/index.js"],
      "env": {
        "ALLOWED_PATHS": "/Users/you/Documents,/Users/you/Projects"
      }
    }
  }
}

Example: Multiple Servers

You can configure multiple servers that will all be available to Claude:

json

{
  "mcpServers": {
    "mcp-tools": {
      "command": "python3",
      "args": ["/path/to/stdio_example.py"]
    },
    "calculator": {
      "command": "python3",
      "args": ["/path/to/calculator_example.py"]
    },
    "files": {
      "command": "python3",
      "args": ["/path/to/file_example.py"]
    }
  }
}

Security Note

The configuration file may contain sensitive information like API keys. Make sure this file has appropriate permissions and is not committed to version control. Consider using environment variable references where possible.

Using Absolute Paths

Always use absolute paths in your configuration. Relative paths can cause issues because Claude Desktop's working directory is not guaranteed:

json

// Good - absolute path
"args": ["/Users/you/projects/server.py"]

// Bad - relative path (may not work)
"args": ["./server.py"]
"args": ["~/projects/server.py"]  // ~ expansion may not work

Python Interpreter Path

If you're using a virtual environment or a specific Python installation, you may need to specify the full path to the interpreter:

json

{
  "mcpServers": {
    "my-server": {
      "command": "/Users/you/projects/mcp-server/.venv/bin/python",
      "args": ["/Users/you/projects/mcp-server/server.py"]
    }
  }
}

Finding Python Path

To find the path to your Python interpreter, activate your virtual environment and run which python (macOS/Linux) or where python (Windows).

Server Names

The server name (the key in the mcpServers object) is how you'll identify the server in logs and potentially in Claude's responses. Choose descriptive names:

Use lowercase letters, numbers, and hyphens
Make names descriptive of the server's function
Keep names relatively short
Examples: "calculator", "mcp-tools", "file-browser", "postgres-db"

Configuration Schema

Here's the complete structure of the configuration file:

typescript

interface ClaudeDesktopConfig {
  mcpServers: {
    [serverName: string]: {
      command: string;      // Required: executable path or command
      args?: string[];      // Optional: command-line arguments
      env?: {               // Optional: environment variables
        [key: string]: string;
      };
    };
  };
}

What's Next?

Now that you understand the configuration file format, let's add your MCP server to the configuration and connect it to Claude Desktop.