Tutorial4 min readMay 5, 2026

How to Add an MCP Server via the claude mcp add CLI

Claude Code ships a `claude mcp add` command that attaches an MCP server in one shell line — no JSON editing, no quitting and reopening. This is the fastest way to get a server connected for personal use, and the cleanest way to scaffold the entries that eventually live in .mcp.json.

Goal

Attach an MCP to Claude Code without editing JSON

Time

~2 minutes

Prereq

Claude Code installed and on PATH

Steps

Confirm Claude Code is installed

Run `claude --version` in any terminal. If the command is found, you have Claude Code. If not, install it from claude.com/claude-code first — `claude mcp add` is part of the same CLI.

claude --version

Run claude mcp add with a name and command

The shape is: `claude mcp add <name> -- <command> [args...]`. Everything after `--` is the exact command Claude Code should launch when starting the server. Any install snippet from a top-mcps.com detail page works as the right-hand side.

claude mcp add filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem ~/code

Pass tokens via --env, never inline

Use --env KEY=VALUE for each environment variable the server needs. Tokens passed this way live in your Claude Code config (per-user, not per-repo) and never appear in process listings. Use shell variable substitution to keep the token out of your shell history.

claude mcp add github \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN \
  -- npx @github/github-mcp-server

Pick the scope with --scope (optional)

Default scope is "user" — applies across every project. Add --scope project to write to .mcp.json at the current repo root instead, so the entry is committed with the code and shared with your team. Default to user scope unless you specifically want to share.

claude mcp add postgres \
  --scope project \
  -- npx -y @modelcontextprotocol/server-postgres \
  postgresql://user:pass@localhost/db

Verify with /mcp inside Claude Code

Open a Claude Code session and run the /mcp slash command. You should see your server with a green status and a tool count above zero. From the shell, `claude mcp list` shows the same info plus the underlying error message if a server failed to start.

/mcp

Use --scope project to commit team-shared MCPs

Adding a server with --scope project writes to .mcp.json at the repo root instead of your user config. Commit the file and every contributor gets the same MCP next time they run Claude Code in the repo. Default to user scope for personal tools; opt into project scope only when sharing is the goal.

Useful claude mcp commands

Common subcommands

# List every connected MCP, with status and tool counts
claude mcp list

# Add a stdio-based server (default)
claude mcp add <name> -- <command> [args...]

# Add a remote HTTP/SSE server
claude mcp add <name> --transport http -- https://example.com/sse

# Pass environment variables
claude mcp add <name> --env KEY=VALUE -- <command>

# Switch scope to .mcp.json at the current repo root
claude mcp add <name> --scope project -- <command>

# Remove or disable a server
claude mcp remove <name>
claude mcp disable <name>

When it does not work

"claude: command not found"

Claude Code is not installed or not on PATH. Install from claude.com/claude-code; the installer typically adds the binary to /usr/local/bin or ~/.local/bin. Reopen the terminal after install so the PATH refreshes.

Server added but red status in /mcp

Run `claude mcp list` from the shell. The output includes the actual error — usually a missing binary, wrong package name, or unset env var. Fix the issue, run `claude mcp remove <name>` to wipe the broken entry, then re-add.

--env value contains special characters

Wrap the value in single quotes: --env API_KEY='sk-abc/def$xyz'. Bash expands $var inside double quotes, which leaks shell variables into the value unintentionally. Single quotes pass the value verbatim.

Project-scoped server not visible to teammates

Make sure .mcp.json was committed (not just generated locally) and teammates pulled the latest commit. Claude Code only auto-discovers .mcp.json at the repo root — nested directories are ignored.

FAQ

What is the difference between `claude mcp add` and editing .mcp.json directly?

They write to different places. `claude mcp add` defaults to your user-wide config (applied across every project). Editing .mcp.json at the repo root scopes the server to that repo. Use --scope project on the CLI to write to .mcp.json instead, or just edit the file directly.

Can I add a remote (HTTP) MCP server through the CLI?

Yes. Pass --transport http (or sse) and the URL: `claude mcp add my-remote --transport http -- https://my-mcp.example.com/sse`. Stdio is the default and assumes a local command.

How do I remove or disable a server I added with the CLI?

`claude mcp remove <name>` deletes the entry. `claude mcp disable <name>` keeps the entry but stops launching the server. Both commands work for both user-scoped and project-scoped entries.

Does `claude mcp add` work in Claude Desktop or Cursor?

No. The CLI is part of Claude Code only. Claude Desktop reads claude_desktop_config.json directly; Cursor reads ~/.cursor/mcp.json. For those clients, edit the JSON file by hand or use a snippet from a top-mcps.com detail page.

Next steps

The CLI works for personal MCPs. For team-shared servers, the project-scoped .mcp.json deserves its own walkthrough.

Best MCPs for Claude Code Build your first MCP →