$How to Setup a Custom MCP Server on Claude Desktop (Mac)

MCP (Model Context Protocol) lets Claude Desktop talk to external tools running on your machine. Think file systems, databases, APIs, or your own custom server. Instead of Claude just chatting, it can actually do things on your computer.

Here's how to set it up on Mac — and a few gotchas I ran into.

What You Need

• Claude Desktop installed (latest version)
• Your MCP server ready to run (Node.js, Python, or any stdio-compatible binary)

The Config File

Claude Desktop reads MCP server configs from:

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

You can also get to it from Claude menu → Settings → Developer → Edit Config.

Config Format

Here's a minimal example using a Python MCP server:

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

A Node.js server would look like:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Desktop"]
    }
  }
}

You can also pass environment variables:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

Important: Use Full Paths

This tripped me up. Relative paths like ./venv/bin/python don't work reliably. Always use full absolute paths:

{
  "command": "/Users/parish/Dev/gen-api/.venv/bin/python",
  "args": ["/Users/parish/Dev/gen-api/mcp_server.py"]
}

After Editing the Config

1. Save the file
2. Fully quit Claude Desktop (Cmd+Q, not just close the window)
3. Make sure your MCP server can actually run (test it in terminal first)
4. Relaunch Claude Desktop

If it worked, you'll see a hammer icon or MCP indicator near the chat input. Click it to see the available tools.

What Works

• command + args format — Claude Desktop spawns the process using stdio transport
• Multiple servers — add as many as you want inside mcpServers
• Environment variables — use the env field
• Desktop Extensions (.mcpb) — one-click install packages, browse them in Settings → Extensions
• Tools, resources, and prompts — all standard MCP features are supported

What Doesn't Work

• url based config — Claude Desktop does NOT support "url": "http://localhost:8000/mcp/sse" in the config file. It expects a command field. Without it, you get a validation error about command being required.
• Remote SSE servers in config — if your server runs as a remote HTTP/SSE endpoint, you can't just point to it in the JSON. You need to either wrap it with a local stdio proxy or use Settings → Connectors → Add custom connector for remote servers.
• Claude Code shares configs — Claude Code (~/.claude.json) and Claude Desktop have completely separate MCP configs. Adding a server to one doesn't make it available in the other. You can import Desktop servers into Claude Code with claude mcp add-from-claude-desktop.

Debugging

If your server doesn't show up:

• Check the logs at ~/Library/Logs/Claude/mcp-server-*.log
• Try running your server command manually in terminal to see if it errors
• Make sure the JSON is valid (a trailing comma will break it)
• Restart Claude Desktop completely

Quick Recap

1. Edit ~/Library/Application Support/Claude/claude_desktop_config.json
2. Use command + args format with full paths
3. Restart Claude Desktop
4. Look for the MCP indicator in chat

That's it. Once connected, Claude can use whatever tools your server exposes — file operations, API calls, code execution, whatever you build.