Chapter 7: Connecting to Claude Desktop

Claude Desktop is the primary desktop application for interacting with Claude. It has built-in MCP support and can connect to any number of MCP servers simultaneously. This chapter covers how to configure Claude Desktop to use your server.

The Configuration File

Claude Desktop reads MCP server configuration from a JSON file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

If this file does not exist, create it. Claude Desktop reads it at startup and each time you restart the application.

Connecting a Local stdio Server

For a server that runs as a local process (stdio transport), add it under the mcpServers key:

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/absolute/path/to/your/server.py"]
    }
  }
}

• "my-server" is the display name in the Claude Desktop UI
• "command" is the executable to run
• "args" is the list of arguments

Always use absolute paths. Claude Desktop does not inherit your shell’s PATH or working directory, so relative paths will fail silently.

Using a Virtual Environment

If your server has dependencies installed in a virtual environment:

{
  "mcpServers": {
    "my-server": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Point "command" directly to the Python interpreter inside the venv.

Using uv (Recommended)

uv is a fast Python package manager that handles virtual environments automatically. The mcp install command uses uv under the hood:

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/server-project",
        "run", "server.py"
      ]
    }
  }
}

uv creates an isolated environment, installs dependencies from pyproject.toml, and runs the server — all automatically.

Automatic Installation With mcp install

The MCP CLI can generate the config entry for you:

mcp install /path/to/server.py --name "My Server"

This adds the correct entry to claude_desktop_config.json automatically. If your server uses FastMCP(dependencies=[...]), the required packages are also installed.

Environment Variables

Pass environment variables to your server (for API keys, config, etc.):

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb",
        "API_KEY": "sk-..."
      }
    }
  }
}

Never hardcode secrets in the config file if it is shared or version-controlled. Use a secrets manager or environment variable injection at the OS level.

Connecting a Remote HTTP/SSE Server

For a server running over HTTP/SSE:

{
  "mcpServers": {
    "remote-server": {
      "url": "https://my-mcp-server.example.com/sse"
    }
  }
}

No command or args are needed — Claude Desktop connects to the running HTTP server directly.

Multiple Servers

You can connect to multiple servers at once:

{
  "mcpServers": {
    "database-tools": {
      "command": "python",
      "args": ["/path/to/db_server.py"]
    },
    "file-tools": {
      "command": "python",
      "args": ["/path/to/file_server.py"]
    },
    "web-search": {
      "url": "https://search-mcp.example.com/sse"
    }
  }
}

Claude Desktop starts all configured servers when it launches and makes all their tools available to Claude simultaneously. Tool names must be unique across all connected servers.

Verifying the Connection

After editing the config:

1. Fully quit and relaunch Claude Desktop (not just close the window)
2. Open a new conversation
3. Look for the tools icon (a hammer or plug icon) in the chat interface
4. Click it to see which tools are available

If a server fails to start, Claude Desktop shows an error notification. Check:

• The path to your server file is correct and absolute
• The Python interpreter path is correct
• Dependencies are installed in the target environment
• There are no syntax errors in your server file

Troubleshooting

Server not appearing in tools list:

• Confirm the config file is valid JSON (use a JSON validator)
• Restart Claude Desktop completely
• Check that the server file exists at the given path

Tools appear but calls fail:

• Run the server directly in a terminal to see stderr output
• Use mcp dev server.py to test the server interactively

“spawn ENOENT” or similar process errors:

• The command path is wrong or not executable
• Use the full absolute path to the Python interpreter

Server starts but immediately exits:

• Your server is crashing on startup
• Run it directly in a terminal to see the error output

Key Takeaways

• Edit claude_desktop_config.json to add MCP servers
• Use absolute paths for all file references
• For local servers: specify command and args
• For remote servers: specify url
• Pass secrets via env (not hardcoded in the file)
• Use mcp install for automatic config generation
• Restart Claude Desktop after every config change