Connecting to Claude Desktop

Step-by-step guide to configuring Claude Desktop to use your MCP server. Learn how to edit the configuration file, troubleshoot connections, and verify your tools are working.

title: "Connecting to Claude Desktop" description: "Step-by-step guide to configuring Claude Desktop to use your MCP server. Learn how to edit the configuration file, troubleshoot connections, and verify your tools are working." order: 7 level: "beginner" duration: "8 min" keywords:

• Claude Desktop MCP
• configure Claude Desktop
• MCP server configuration
• claude_desktop_config.json
• connect MCP server
• Claude Desktop setup
• MCP client configuration date: "2026-04-01"

What Is Claude Desktop?

Claude Desktop is Anthropic's standalone application for interacting with Claude. Unlike the web interface at claude.ai, the desktop app supports MCP natively — it can connect to local MCP servers and use their tools, resources, and prompts directly in conversations.

How Do You Configure Claude Desktop for MCP?

Claude Desktop reads its MCP server configuration from a JSON file. The location depends on your operating system.

cd /path/to/your/weather-server
npm run build

{
  "mcpServers": {
    "weather-server": {
      "command": "node",
      "args": ["/absolute/path/to/weather-server/dist/index.js"]
    }
  }
}

Understanding the Configuration Format

The claude_desktop_config.json file follows this structure:

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

Configuration Fields

| Field | Required | Description | |-------|----------|-------------| | command | Yes | The executable to run. Usually node for TypeScript/JavaScript servers. | | args | Yes | Command-line arguments. For Node.js servers, this is the path to your compiled entry point. | | env | No | Environment variables to pass to the server process. |

Multiple Server Configuration

You can configure multiple MCP servers at once. Each server runs as a separate process:

{
  "mcpServers": {
    "weather-server": {
      "command": "node",
      "args": ["/path/to/weather-server/dist/index.js"]
    },
    "database-server": {
      "command": "node",
      "args": ["/path/to/database-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    },
    "github-tools": {
      "command": "node",
      "args": ["/path/to/github-tools/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Passing Environment Variables

Many MCP servers need API keys or configuration values. Use the env field to pass these securely:

{
  "mcpServers": {
    "api-server": {
      "command": "node",
      "args": ["/path/to/api-server/dist/index.js"],
      "env": {
        "API_KEY": "your-api-key",
        "API_BASE_URL": "https://api.example.com",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Your server code can then access these with process.env:

async execute(input: MyInput) {
  const apiKey = process.env.API_KEY;
  if (!apiKey) {
    return JSON.stringify({
      error: "API_KEY environment variable is not set"
    });
  }

  const response = await fetch(`${process.env.API_BASE_URL}/data`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  // ...
}

Using npx for Published Packages

If your MCP server is published to npm, you can use npx instead of pointing to a local build:

{
  "mcpServers": {
    "my-published-server": {
      "command": "npx",
      "args": ["-y", "my-published-mcp-server"]
    }
  }
}

The -y flag tells npx to automatically confirm the install. This is convenient for sharing MCP servers with others — they just need to add the npx configuration.

Troubleshooting Connection Issues

Server Does Not Appear in Claude Desktop

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

node -e "console.log(JSON.parse(require('fs').readFileSync('path/to/config.json', 'utf8')))"

node /path/to/your/dist/index.js

tail -f ~/Library/Logs/Claude/mcp*.log

Server Connects but Tools Do Not Work

If the server appears connected but tools are not functioning:

• Check your tool names — Ensure they match what you expect. Use MCP Inspector to verify.
• Check the execute method — Make sure it does not throw unhandled errors.
• Verify the build is current — Run npm run build again and restart Claude Desktop.
• Check stderr output — Add console.error("Tool called:", input) for debugging.

Environment Variables Not Working

If your server cannot access environment variables:

• Verify the env field is at the same level as command and args
• Check for typos in variable names
• Restart Claude Desktop after any config changes
• Test with a simple tool that returns process.env.YOUR_VAR

Complete Example: Weather Server Configuration

Here is the complete end-to-end setup for the weather server we built earlier:

1. Build the Server

cd /Users/yourname/projects/weather-server
npm run build

2. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "weather-server": {
      "command": "node",
      "args": ["/Users/yourname/projects/weather-server/dist/index.js"]
    }
  }
}

3. Restart Claude Desktop

Close and reopen the application.

4. Test the Connection

Start a new conversation and ask:

"Can you check the weather in London and give me a 3-day forecast?"

Claude should call both get_weather and get_forecast tools and present the results naturally.

Managing Server Lifecycle

Claude Desktop manages the lifecycle of your MCP servers:

• Startup — Servers are started when Claude Desktop launches (or when the config is first loaded)
• Communication — Messages flow over stdio between Claude Desktop and your server process
• Shutdown — Servers are terminated when Claude Desktop closes

You do not need to start or stop your server manually. Claude Desktop handles everything.

Security Considerations

When connecting MCP servers to Claude Desktop, keep these security practices in mind:

• Audit server code before connecting — MCP servers can execute arbitrary code on your machine
• Limit permissions — Only give servers access to the data and APIs they need
• Review environment variables — Do not pass credentials to servers that do not need them
• Use read-only database connections where possible
• Be cautious with third-party servers — Only connect servers from trusted sources

Claude Desktop is set up and running your MCP server. Next, learn how to connect to code editors — head to Connecting to Cursor and VS Code for IDE integration.