Importing MCP server setup from Claude Desktop to Claude Code

The quick answer

Run claude mcp add-from-claude-desktop from your terminal. It reads Claude Desktop's config, shows an interactive checklist of the servers it found, and writes the ones you pick into Claude Code. Add --scope user if you want them available in every project instead of just the current one. Then run claude mcp list to confirm they connected.

# Interactive import: pick which Desktop servers to bring over
$claude mcp add-from-claude-desktop
 
# Same, but make the imported servers available in all your projects
$claude mcp add-from-claude-desktop --scope user
 
# Verify
$claude mcp list

One caveat to know before you start: add-from-claude-desktop only works on macOS and Windows Subsystem for Linux (WSL). It reads Claude Desktop's config from the standard location on those platforms. On native Linux there's a manual path below. (Claude Code MCP docs: Import MCP servers from Claude Desktop)

Why this isn't just "copy the file over"

Claude Desktop and Claude Code are different applications that read different config files in different formats, so there is no file you can simply drop into place. This is the single fact that trips people up, so it's worth being precise about where each side keeps its servers.

Claude Desktop stores its servers in one JSON file (Connect to local MCP servers, modelcontextprotocol.io):

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

That file is a flat { "mcpServers": { ... } } object; every server is global to Desktop.

Claude Code does not read claude_desktop_config.json at all. It keeps MCP servers in one of three places depending on the scope you choose (Claude Code MCP docs: installation scopes):

If you've read another guide that told you to paste servers into claude_desktop_config.json to configure Claude Code, that's wrong. Claude Code never reads that file, and edits to it do nothing in the CLI. The import command exists precisely because the two formats and locations don't line up.

Step 1: Make sure your Desktop servers are working first

Import copies configuration, not health. A server that was silently failing in Claude Desktop will arrive in Claude Code just as broken. Before you migrate, open Claude Desktop, confirm the servers you care about actually show their tools, and skim the Desktop MCP logs for any that don't (Connect to local MCP servers, modelcontextprotocol.io). On macOS:

# macOS — tail Claude Desktop's MCP logs
$tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

On Windows the same logs live in %APPDATA%\Claude\logs.

It's also worth knowing what won't transfer cleanly. The import brings over the server definition (command, args, and env) verbatim. Two things to watch:

• Relative paths and shell aliases. If a Desktop server's command relies on your shell's PATH or a relative path, it may resolve differently when Claude Code launches it. Prefer absolute paths (e.g. the full path to node or your server script).
• Secrets in env. API keys stored in the Desktop config come along as plain values. That's fine for local/user scope (which stay in your home directory), but if you later move a server to project scope and commit .mcp.json, you'd be committing the key. Use environment-variable expansion instead ("env": { "API_KEY": "${MY_API_KEY}" }) for anything checked into version control. (Claude Code MCP docs: environment variable expansion)

Step 2: Run the import and choose a scope

$claude mcp add-from-claude-desktop

You'll get an interactive checklist of the servers found in Claude Desktop. Pick the ones to bring over. By default they're added at local scope, meaning they only load in the project you ran the command from, stored under that project's entry in ~/.claude.json.

That default is usually not what someone migrating from Desktop wants. In Desktop, your servers were available everywhere; the equivalent in Claude Code is user scope:

$claude mcp add-from-claude-desktop --scope user

There is no global scope in Claude Code; the value that makes a server available across all your projects is user. The three valid scopes are local, project, and user. (Claude Code MCP docs: installation scopes)

Use project scope (not available directly through add-from-claude-desktop, but easy to set up afterward, see below) only when you want to share a server with teammates by committing it to the repo.

A detail that saves confusion later: if a server name already exists in Claude Code, the import doesn't overwrite it. It appends a numeric suffix, so you'll see something like github_1. (Claude Code MCP docs: Import MCP servers from Claude Desktop)

Step 3: Verify the import worked

Two checks, one from the shell and one from inside a session.

# Lists every configured server and whether it connected
$claude mcp list
 
# Inspect a single server's full config
$claude mcp get github

claude mcp list shows each server with a connection status, so a server that imported but can't start is immediately visible. (Claude Code MCP docs)

Then, inside an interactive Claude Code session, run the slash command:

/mcp

/mcp opens an interactive panel listing your connected servers and their tools (and is where you complete OAuth for any remote servers). If a server shows up in claude mcp list but its tools aren't in /mcp, the process started but failed to register. Check the command path and env values you carried over from Desktop. (Claude Code MCP docs)

When import isn't available: native Linux and edge cases

add-from-claude-desktop only reads Desktop's config on macOS and WSL. On native Linux (or any time you'd rather migrate by hand), add each server explicitly with claude mcp add rather than copying files.

Do not cp claude_desktop_config.json over ~/.claude.json. ~/.claude.json holds all of Claude Code's state (projects, history, and settings, not just MCP servers), so overwriting it wipes that state, and the two files have different shapes anyway. Re-add each server instead:

# A stdio server (local process). Everything after -- runs the server untouched.
$claude mcp add --scope user filesystem \
$  -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
 
# A stdio server that needs an API key in its environment
$claude mcp add --scope user --env BRAVE_API_KEY=your-key brave-search \
$  -- npx -y @modelcontextprotocol/server-brave-search
 
# A remote server over Streamable HTTP (GitHub's endpoint needs a PAT)
$claude mcp add --transport http --scope user github https://api.githubcopilot.com/mcp/ \
$  --header "Authorization: Bearer YOUR_GITHUB_PAT"

The -- separates Claude Code's own flags (--scope, --env, --transport) from the command that launches the server; everything after -- is passed to the server as-is. (Claude Code MCP docs: add stdio servers)

To copy a definition verbatim out of claude_desktop_config.json, claude mcp add-json takes the same per-server JSON shape Desktop uses, so you can paste one server's object directly:

$claude mcp add-json --scope user filesystem \
$  '{"type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/Users/you/Documents"]}'

This is also the cleaner approach on macOS/WSL when you only want one server and don't feel like clicking through the interactive checklist. (Claude Code MCP docs: add servers from JSON)

Sharing imported servers with your team (project scope)

The import and the commands above default to private (local/user) configs in your home directory. To share a server with collaborators, put it at project scope, which writes a .mcp.json file at the repo root that you commit:

$claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp

The resulting .mcp.json is the same { "mcpServers": { ... } } shape as Desktop's file. When a teammate opens the project, Claude Code prompts them to approve project-scoped servers before they run; you can reset those approvals with claude mcp reset-project-choices. Keep secrets out of committed .mcp.json by using ${VAR} expansion as noted above. (Claude Code MCP docs: project scope)

A note on stale GitHub instructions

If your Desktop config (or an older tutorial) uses @modelcontextprotocol/server-github, that reference server was archived in May 2025 and is no longer maintained. The current, official GitHub server is GitHub's own, available as a remote Streamable HTTP endpoint at https://api.githubcopilot.com/mcp/ (shown in the HTTP example above) or self-hosted from github/github-mcp-server. Importing the archived stdio package will still "work," but you're better off re-adding GitHub via the remote endpoint.

What to remember

• Claude Code does not read claude_desktop_config.json; it keeps servers in ~/.claude.json (local/user) or .mcp.json (project).
• claude mcp add-from-claude-desktop is the supported one-command import; it's interactive and macOS/WSL only.
• Add --scope user to mirror Desktop's "available everywhere" behavior; local (the default) is per-project, and there is no global scope.
• On native Linux, re-add servers with claude mcp add / add-json; never overwrite ~/.claude.json.
• Verify with claude mcp list and /mcp before assuming a server made the trip intact.