Claude Desktop & MCP Cheat Sheet

1Install & sign inmacOS · Windows

# download from: claude.ai/download★
Native app for macOS and Windows (there's no official Linux desktop build). Sign in with the same account as claude.ai — your plan (Free/Pro/Max/Team) carries over.
# updates install automatically; relaunch to apply
The app self-updates. Feature availability (Connectors, Extensions, Developer mode) can differ by app version and plan — keep it current.
# the desktop app is NOT Claude Code (that's a separate CLI)
Claude Desktop is the chat GUI + MCP host. Claude Code is the agentic coding tool for the terminal/IDE — different product, also an MCP host.

2Interface & featureswhat's built in

Projects # persistent workspaces with their own knowledge + instructions★
Group chats, upload reference docs (project knowledge), and set custom instructions that apply to every chat in the project.
Artifacts # live side panel for code, docs, HTML, diagrams★
Substantial generated content opens in a dedicated panel you can iterate on — runnable HTML/React previews, editable documents.
Styles · web search · file & image uploads
Styles shape tone/format (Normal, Concise, Explanatory, or custom). Attach files/images with the paperclip; toggle web search per chat.
# model + extended-thinking toggle live under the message box
Pick the model and turn extended thinking on for harder problems right where you type.

3The config fileclaude_desktop_config.json

Settings → Developer → Edit Config★
The reliable way to open (and create, if missing) claude_desktop_config.json — it reveals the file in Finder/Explorer. This is where all local MCP servers are declared.
# macOS ~/Library/Application Support/Claude/claude_desktop_config.json★
The file's home on macOS. It does not exist until you create it (or click Edit Config once).
# Windows %APPDATA%\Claude\claude_desktop_config.json★
On Windows, expand %APPDATA% (usually C:\Users\<you>\AppData\Roaming). Same JSON schema on both platforms.
{ "mcpServers": { } }
The whole file is one JSON object. Servers go under the mcpServers key — empty is valid. ⚠️ It must be strict JSON: no comments, no trailing commas.

4Settings & shortcutsget around fast

Cmd/Ctrl + N # new chat Cmd/Ctrl + K # quick search★
Start a fresh conversation or jump to any past chat instantly.
Cmd/Ctrl + , # open Settings
Settings holds account, model behavior, Connectors, Extensions, and Developer (where Edit Config lives). Enable Developer mode if you don't see it.
Cmd/Ctrl + Shift + Enter # some builds: quick-launch capture
The app can stay resident in the menu bar / system tray for fast access. Exact shortcuts vary by platform & version — check Settings.

5Add a local serverstdio via command/args

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"] } } }★
The canonical shape: each server is a name → {command, args}. The app launches that process and talks MCP over stdio. Restart Claude Desktop after saving.
"command": "node", "args": ["/abs/path/to/build/index.js"]★
Run your own server the same way. ⚠️ Use absolute paths and an absolute command when possible — the app may not inherit your shell's PATH.
# "server disconnected" right after launch? almost always PATH/pathsgotcha
If npx/uvx/node isn't found, give the full binary path (e.g. /opt/homebrew/bin/npx, or the full node.exe path on Windows). Check the logs (card 11).

6Common serversready-made

npx -y "@modelcontextprotocol/server-filesystem" /path/one /path/two★
Filesystem — read/write files in the directories you list (scoped to exactly those paths). The most-installed first server.
uvx mcp-server-git --repository /path/to/repo
Git — inspect and operate on a repo. Python servers commonly launch via uvx (from uv) instead of npx.
# many first- & third-party servers: Postgres, Slack, GitHub, Puppeteer, memory…
Browse the registry at modelcontextprotocol.io and the reference servers repo. ⚠️ MCP servers run with your privileges — only install ones you trust.

7Secrets & env varskeys into a server

"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "ghp_..." } }★
Pass secrets/config via the env object — it becomes the child process's environment. Servers read tokens from there, not from prompts.
# this file stores tokens in PLAINTEXT — treat it like a secretsecurity
Don't commit claude_desktop_config.json to git; lock down file permissions. Prefer short-lived / least-privilege tokens.
"cwd": "/working/dir" # set the server's working directory
Some servers also accept a cwd. Keep the JSON valid — a single syntax error stops all servers from loading.

8Remote connectorsSettings, no JSON

Settings → Connectors → Add custom connector★
Connectors are remote MCP servers reached by URL — no config file, no local process. Add a URL and (usually) authorize via OAuth in the browser.
# built-in connectors for popular apps may appear here too
Depending on plan & availability, ready-made connectors (Google Drive, etc.) can be toggled on directly — no setup beyond signing in.
# local servers = config file; remote servers = Connectors UI
Rule of thumb: a process on your machine goes in claude_desktop_config.json; a hosted URL goes in Connectors.

9Desktop Extensionsone-click install

Settings → Extensions # install a packaged MCP server (.mcpb / .dxt)★
Desktop Extensions bundle an MCP server + its runtime into one installable file — no manual JSON, no npx. The app manages its lifecycle.
# configure keys/paths via the extension's own settings form
Extensions expose their settings in the UI, so you set tokens/paths through a form instead of hand-editing env. Easiest path for non-developers.
# three ways in: config JSON · Connectors · Extensions
Pick by comfort: JSON (max control), Connectors (remote/OAuth), Extensions (one-click local). They can coexist.

10Using tools in chatpermissions

# tools appear behind the tools/slider icon by the message box★
Once a server loads, its tools become available. Claude decides when to call them; you'll see the tool call and its result inline in the chat.
# Claude asks permission before running a tool★
You approve tool calls — grant once, or "always allow" for that tool. ⚠️ Approving a write/exec tool lets it act on your machine; read the call before allowing.
# tools not showing up? the server didn't loadgotcha
No tools = the server failed to start (bad JSON, missing binary, crash on launch). Fully quit and reopen the app after any config change, then check logs.

11Debugging serversread the logs

# macOS logs ~/Library/Logs/Claude/ # mcp.log, mcp-server-*.log★
Per-server stderr & connection logs land here — the first place to look when a server won't connect. On Windows they're under %APPDATA%\Claude\logs\.
npx @modelcontextprotocol/inspector node /path/to/server.js★
The MCP Inspector runs a server standalone in the browser so you can test its tools without the desktop app — isolate "is it my server or the config?".
# test the launch command in a terminal first
Run the exact command + args in a shell. If it errors there, it'll error in Claude — fix paths/deps before blaming the config.

12Tips & ecosystemget the most out

# validate the JSON before restarting (jq . claude_desktop_config.json)★
One misplaced comma silently kills every server. Lint the file after editing — the app won't always tell you it's malformed.
# MCP is an open standard — the same servers work across hosts
Servers you configure here also work with Claude Code, IDE extensions, and other MCP hosts. Build/learn once, reuse everywhere.
# start narrow: one filesystem dir, least-privilege tokens
Grant the smallest scope that works, then widen. Fewer, well-scoped servers keep the tool list clean and safer.

Claude Desktop & MCP

Outline

App & config

MCP servers

Connectors, use & debug

App & Config

MCP Servers

Connectors, Use & Debug

Worth memorizing