How to remove an MCP server from Claude Code

Run claude mcp remove <name> from the relevant project, with --scope local, user or project to choose the definition. Removing a remote server also deletes its stored OAuth tokens and client registration. To keep the setup for later, turn it off in /mcp instead.

By Miguel Silva · Updated 2026-09-12

The command, and the scope it removes from

claude mcp list                          # what is configured here
claude mcp get <name>                    # transport, command, scope
claude mcp remove <name>                 # whichever scope has it
claude mcp remove <name> --scope local   # this project only
claude mcp remove <name> --scope user    # the whole machine
claude mcp remove <name> --scope project # the repository .mcp.json

The directory matters more than the flag. Local and project scope are both tied to a path, so claude mcp remove run from your home folder cannot see a server added inside a repository. When the name does not resolve, Claude does not fail quietly; it prints the names it can see, which is the fastest way to find out you are in the wrong place.

$ claude mcp remove playwright
No MCP server named "playwright". Configured servers: notebooklm

Where the entry actually was

Three files, and which one held the server decides what is left over after the command returns.

.mcp.json

Project scope, in the repository root, meant to be committed. remove takes the server out of the mcpServers object and writes the file back; it does not delete the file.

~/.claude.json

User scope under a top-level mcpServers object, and local scope under projects, keyed by the absolute path of the project. One file holds both.

.claude/settings.json

Never held the server, but may still name it: enabledMcpjsonServers and disabledMcpjsonServers are lists of names, and removing a server does not tidy them.

What removal leaves behind

Take a project server out and the file stays, holding nothing. That is by design; the repository keeps a place for the next server; but it means an empty .mcp.json is not evidence that something went wrong, and it is a file you may want to delete by hand and commit.

{
  "mcpServers": {}
}

• Current Claude Code removes stored OAuth tokens and client registration when removing a remote server. A separate logout is not required to clear those local credentials.
• Copy the entry first. A stdio server carries a command, its arguments and its environment; an HTTP one carries a URL and its headers. remove takes all of it, and claude mcp get <name> is the last chance to read it.
• Check settings.json. A name left in disabledMcpjsonServers or enabledMcpjsonServers is harmless, but it is a lie about what the project uses, and it is what you will read next time you go looking.
• A local-scope entry outlives its folder. ~/.claude.json is keyed by absolute path and nothing prunes it, so delete the project and its servers stay in the file with no way to reach them: claude mcp remove needs the directory, and the directory is gone.

The entry you cannot reach from the terminal

That last one is the case with no command behind it. A server added at local scope to a project you have since deleted is still in ~/.claude.json, still listed under the old path, and claude mcp remove cannot touch it because there is no directory left to run it from. Recreating the folder just to delete the entry works and feels ridiculous; the alternative is hand-editing a file that has a block for every project you have ever opened.

This is the gap Loadout closes. It reads the file rather than the folder, so orphaned entries appear in the MCP list alongside the live ones and delete like anything else, whatever became of the project they belonged to. The same list is where you turn a server off instead, and where the usage count tells you which of the two the server deserves.

When you wanted it off, not gone

Most people typing "remove mcp" want the server to stop loading, not to lose its configuration. There is no claude mcp disable; the subcommands are add, add-json, add-from-claude-desktop, get, list, login, logout and remove; but there are two ways to switch a server off with the entry left where it is. For a project server, name it in disabledMcpjsonServers. For one session, start Claude with --strict-mcp-config, which ignores every MCP configuration except one you pass explicitly.

claude --strict-mcp-config      # no MCP servers at all, this session

Remove is the right command when the server is genuinely finished with: a tool you tried once, a service you no longer pay for, a server whose credentials you have just rotated. It is the wrong one for a server you are muting for a fortnight, because getting it back is a small archaeology job.

Questions

How do I remove an MCP server from Claude Code?

Run claude mcp remove <name> from the project the server belongs to. With no --scope it removes the server from whichever scope defines it; pass --scope local, user or project to be explicit. If Claude replies that no server by that name is configured, you are in the wrong directory.

Does claude mcp remove delete the .mcp.json file?

No. It takes the server out of the mcpServers object and writes the file back, so removing the last server leaves a .mcp.json containing an empty mcpServers object. Delete the file by hand if you want it gone from the repository.

How do I remove an MCP server whose project folder is gone?

Not with claude mcp remove: local-scope servers are stored in ~/.claude.json under the absolute path of the project, and the command needs that directory to exist. Either edit the file by hand, or delete the entry in Loadout, which lists MCP servers from the file rather than from the folder.

How do I remove an MCP server without losing its configuration?

Open /mcp, select the server and turn it off. The definition stays saved and the choice is recorded per project. Use the disable guide for session-only options and managed-configuration limits.