Seongwoo Choi / Journal

Claude Code plugins and MCP servers: a terminal guide

At a glanceAdd MCP servers and install plugins in Claude Code from the terminal, on macOS and in Windows Terminal: commands, scopes, secrets, and real command output.

TestedEvery command shown with output was run with Claude Code 2.1.322 on Linux. The macOS, Windows and sign-in steps are from the documentation.

You need
Claude Code installed on macOS or Windows, a terminal, and Python 3 for the practice server.
You end up with
One remote and one local MCP server connected, one plugin installed, and the commands to manage both.
In this article 12 sections
  1. 1. Plugin or MCP server: which is which
  2. 2. Set up the terminal on macOS and Windows
  3. 3. Add a remote MCP server
  4. 4. Add a local MCP server, with a practice server
  5. 5. Choose who gets the server: three scopes
  6. 6. Manage your servers
  7. 7. Install a plugin
  8. 8. Add another marketplace
  9. 9. Practice the whole plugin loop offline
  10. 10. Update, disable and remove
  11. 11. When something does not work
  12. 12. What you can do now

Out of the box, Claude Code can read your files and run commands. Two additions make it far more useful: MCP servers, which connect it to outside tools such as an issue tracker or a database, and plugins, which package ready-made skills and commands. Both are managed from the terminal with a handful of commands. This guide walks through them on macOS and Windows, using output from real runs.

1. Plugin or MCP server: which is which

Youtype a request
→
Claude Codein your terminal
→
MCP servera connector Claude can call
→
Outside toolNotion, GitHub, a database
An MCP server is a connector. A plugin is a package that can add skills, agents, hooks and MCP servers in one install.
MCP serverPlugin
What it isOne connection to one tool or serviceA bundle: skills, agents, hooks, and sometimes MCP servers
Where it comes fromThe service itself, or a program you runA marketplace, which is a catalog of plugins
Shell commandclaude mcp ...claude plugin ...
Inside a session/mcp/plugin

The commands come in two forms. Those starting with claude are typed in your normal shell. Those starting with / are typed inside a running Claude Code session.

2. Set up the terminal on macOS and Windows

macOSWindows
Terminal to useTerminal, or iTerm2Windows Terminal with PowerShell
Installcurl -fsSL https://claude.ai/install.sh | bashirm https://claude.ai/install.ps1 | iex
Package manager alternativebrew install --cask claude-codewinget install Anthropic.ClaudeCode
Also installNothingGit for Windows, recommended so Claude Code can use Bash; without it, it uses PowerShell
New line in a promptShift+Enter works in Apple TerminalShift+Enter works in Windows Terminal
One setting to checkSettings → Profiles → Keyboard → "Use Option as Meta Key"If Backspace deletes a whole word, set CLAUDE_CODE_BS_AS_CTRL_BACKSPACE=0

The macOS setting matters because several shortcuts use the Option key, and Terminal does not send it as a modifier by default. If you accepted the terminal setup prompt on first run, it is already on. On any terminal, Ctrl+J also inserts a new line.

On Windows, the PowerShell prompt starts with PS C:\. If the install command reports that irm is not recognized, you are in the older CMD shell; the documentation has a separate command for it.

Then check the installation. Open a new terminal window first, so it picks up the new command:

$ claude --version
2.1.322 (Claude Code)

claude doctor gives a fuller health check without starting a session. Run claude once in a project folder and sign in before continuing.

3. Add a remote MCP server

Most services offer a hosted server reached over HTTP. One command registers it. This one is the documentation's own example:

claude mcp add --transport http notion https://mcp.notion.com/mcp

The pattern is always claude mcp add --transport http <name> <url>. The name is yours to choose; it is how you refer to the server later.

Registering is not signing in. Start a session with claude, type /mcp, select the server and complete the sign-in in your browser. Servers that need attention are flagged in that panel.

For a service that uses a fixed key instead of a browser sign-in, pass it as a header:

claude mcp add --transport http my-api https://api.example.com/mcp --header "Authorization: Bearer YOUR_TOKEN"
One lineKeep these commands on a single line. Line-continuation characters differ between shells: a backslash in macOS and Linux shells, a backtick in PowerShell. A one-line command works in all of them.

4. Add a local MCP server, with a practice server

A local server is a program on your own machine that Claude Code starts and talks to. Use it for tools that need direct access to your files or your network. The command has one new element, a double dash:

claude mcp add --transport stdio <name> -- <command to start the server>

Everything before -- is an option for Claude Code. Everything after it is the server's own command, passed through untouched. Without the double dash, Claude Code would try to read the server's flags as its own.

To see the whole loop without installing anything, save this small server as hello_mcp.py. It offers one tool that returns a greeting:

"""A tiny MCP server with one tool, for testing that Claude Code can connect."""
import json
import sys


def send(message):
    sys.stdout.write(json.dumps(message) + "\n")
    sys.stdout.flush()


for line in sys.stdin:
    if not line.strip():
        continue
    request = json.loads(line)
    ident, method = request.get("id"), request.get("method")
    if method == "initialize":
        send({"jsonrpc": "2.0", "id": ident, "result": {
            "protocolVersion": request["params"]["protocolVersion"],
            "capabilities": {"tools": {}},
            "serverInfo": {"name": "hello", "version": "0.1.0"}}})
    elif method == "tools/list":
        send({"jsonrpc": "2.0", "id": ident, "result": {"tools": [{
            "name": "say_hello",
            "description": "Return a greeting for a name",
            "inputSchema": {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}}]}})
    elif method == "tools/call":
        name = request["params"]["arguments"].get("name", "world")
        send({"jsonrpc": "2.0", "id": ident, "result": {"content": [{"type": "text", "text": f"Hello, {name}!"}]}})
    elif ident is not None:
        send({"jsonrpc": "2.0", "id": ident, "result": {}})

Add it, using the full path to the file. On Windows the command is usually python, not python3.

$ claude mcp add --transport stdio hello -- python3 /path/to/servers/hello_mcp.py
Added stdio MCP server hello with command: python3 /path/to/servers/hello_mcp.py to local config
File modified: /path/to/home/.claude.json [project: /path/to/project]

$ claude mcp list
Checking MCP server health…

hello: python3 /path/to/servers/hello_mcp.py - ✔ Connected

$ claude mcp get hello
hello:
  Scope: Local config (private to you in this project)
  Status: ✔ Connected
  Type: stdio
  Command: python3
  Args: /path/to/servers/hello_mcp.py

To remove this server, run: claude mcp remove hello -s local
Real output from Claude Code 2.1.322. Folder names are shortened.

"Connected" means Claude Code started the program and completed the handshake. In a session, you can now ask it to use the hello tool to greet someone, and it will ask your permission before the first call.

Real local servers are usually started with a package runner. The documentation's example passes a key through the environment:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

Put --transport stdio between --env and the name, as shown. The documentation notes that a name placed directly after --env is read as another variable and rejected.

5. Choose who gets the server: three scopes

ScopeLoads inShared with the teamStored in
Local, the defaultThis project onlyNo.claude.json in your home folder
ProjectThis project onlyYes, through version control.mcp.json in the project
UserAll your projectsNo.claude.json in your home folder

Add --scope project or --scope user to change it. Here is the project scope in a real run, and the file it wrote:

$ claude mcp add --transport http notion --scope project https://mcp.notion.com/mcp
Added HTTP MCP server notion with URL: https://mcp.notion.com/mcp to project config
File modified: /path/to/project/.mcp.json

$ cat .mcp.json
{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

$ claude mcp list
notion: https://mcp.notion.com/mcp (HTTP) - ⏸ Pending approval (run `claude` to approve)
hello: python3 /path/to/servers/hello_mcp.py - ✔ Connected

Notice "Pending approval". A file in a repository cannot switch on its own servers. Each person is asked to approve a project's servers the first time they start a session there. That protects you when you clone someone else's repository.

Do not commit secrets.mcp.json is meant to be committed, so keep keys out of it. Write ${API_KEY} in the file and let each person set the variable on their own machine. ${API_KEY:-fallback} supplies a default.

Setting a variable differs by system:

macOS (zsh)Windows (PowerShell)
For this terminal windowexport API_KEY="value"$env:API_KEY = "value"
For every new windowAdd that line to ~/.zshrcsetx API_KEY "value", then open a new window

6. Manage your servers

TaskCommand
List servers with their statusclaude mcp list
Show one server's detailsclaude mcp get <name>
Remove a serverclaude mcp remove <name>
Sign in, reconnect or disable, inside a session/mcp
Add from a JSON snippet in a server's READMEclaude mcp add-json <name> '<json>'
Copy servers from the Claude desktop appclaude mcp add-from-claude-desktop, on macOS and WSL only
Forget approvals for project serversclaude mcp reset-project-choices

Many servers publish their setup as a JSON block. add-json accepts it directly. A remote entry needs a type; the documentation warns that an entry with a url and no type is treated as an error and skipped.

Quoting JSON on a command line differs between shells. If add-json gives you trouble in PowerShell, use the ordinary claude mcp add flags, or put the block in .mcp.json with a text editor.

7. Install a plugin

Plugins come from marketplaces. Anthropic's official one is named claude-plugins-official. Inside a session:

/plugin install commit-commands@claude-plugins-official

That is the documentation's example, a plugin that adds commands for committing and opening pull requests. In a session the command does not install at once. It opens the plugin's details so you can review them and pick a scope. To browse instead, type /plugin alone and use the Discover tab.

ScopeWho gets itRecorded in
UserYou, in every project on this machine~/.claude/settings.json
ProjectEveryone who works in the repository.claude/settings.json, which you commit
LocalYou, in this repository only.claude/settings.local.json

After installing, read the last line of the summary. "Plugin is now active" means it is ready. "Run /reload-plugins to apply" means one more step. Then type / and look for the plugin's skills, named in the form /commit-commands:commit.

The same install works from the shell, which is useful in a setup script:

claude plugin install commit-commands@claude-plugins-official

From the shell the default scope is user; add --scope project or --scope local to change it. On a brand-new machine where no session has been opened yet, the documentation says to register the marketplace first with claude plugin marketplace add anthropics/claude-plugins-official.

Read before you installA plugin can run hooks and start MCP servers on your machine. Install from publishers you trust, and look at what a plugin contains first; step 9 shows the command.

8. Add another marketplace

A plugin from a colleague or a community catalog needs its marketplace added once:

SourceExample
GitHub repositoryclaude plugin marketplace add your-org/plugins
Pinned to a tagclaude plugin marketplace add your-org/plugins#v1.2.0
Any git hostclaude plugin marketplace add https://gitlab.example.com/group/marketplace.git
A folder on your machineclaude plugin marketplace add ./my-marketplace

Start a local path with ./. A bare name/name is read as a GitHub repository. Inside a session, the same commands begin with /plugin marketplace.

9. Practice the whole plugin loop offline

You can try every plugin command without touching the network, using a marketplace in a folder. It needs three small files:

my-marketplace/
  .claude-plugin/marketplace.json
  plugins/hello-plugin/
    .claude-plugin/plugin.json
    skills/hello/SKILL.md

marketplace.json lists the plugins:

{
  "name": "my-marketplace",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "hello-plugin",
      "source": "./plugins/hello-plugin",
      "description": "A greeting skill for testing plugin installation"
    }
  ]
}

plugin.json describes the plugin:

{
  "name": "hello-plugin",
  "description": "A greeting skill for testing plugin installation",
  "version": "0.1.0"
}

And SKILL.md is the skill itself:

---
name: hello
description: Greet the user by name. Use when the user asks for a greeting.
---

Reply with one friendly sentence that greets the user by the name they gave.

Then run the loop. This is the real output:

$ claude plugin validate ./my-marketplace
Validating marketplace manifest: /path/to/my-marketplace/.claude-plugin/marketplace.json

⚠ Found 2 warnings:

  ❯ description: No marketplace description provided. Adding a description helps users understand what this marketplace offers
  ❯ plugins[0] plugin.json → author: No author information provided. Consider adding author details for plugin attribution

✔ Validation passed with warnings

$ claude plugin marketplace add ./my-marketplace
Adding marketplace…✔ Successfully added marketplace: my-marketplace (declared in user settings)

$ claude plugin install hello-plugin@my-marketplace
Installing plugin "hello-plugin@my-marketplace"...✔ Successfully installed plugin: hello-plugin@my-marketplace (scope: user)

$ claude plugin list
Installed plugins:

  ❯ hello-plugin@my-marketplace
    Version: 0.1.0
    Read from: /path/to/my-marketplace/plugins/hello-plugin
    Scope: user
    Status: ✔ enabled

$ claude plugin details hello-plugin@my-marketplace
hello-plugin 0.1.0
  Description: A greeting skill for testing plugin installation
  Source: hello-plugin@my-marketplace

Component inventory
  Skills (1)  hello
  Agents (0)
  Hooks (0)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~38 tok   added to every session
Real output from Claude Code 2.1.322. The warnings are advice, not errors.

claude plugin details is the command to remember. It lists what a plugin adds, including hooks and MCP servers, and estimates how many tokens it costs in every session. Run it on any plugin before you rely on it.

10. Update, disable and remove

TaskCommand
List installed pluginsclaude plugin list
Turn one off without removing itclaude plugin disable <plugin>@<marketplace>
Turn it back onclaude plugin enable <plugin>@<marketplace>
Update one plugin nowclaude plugin update <plugin>@<marketplace>
Remove itclaude plugin uninstall <plugin>@<marketplace>
List, refresh or remove marketplacesclaude plugin marketplace list, update <name>, remove <name>

Plugins from the official marketplace update automatically. For other marketplaces auto-update is off by default, and you can turn it on from the Marketplaces tab of /plugin. A running session keeps the versions it loaded; /reload-plugins applies an update without restarting.

In the practice run, disable, enable and uninstall each answered with one line, such as ✔ Successfully uninstalled plugin: hello-plugin (scope: user).

11. When something does not work

What you seeCauseFix
claude is not found after installingThe terminal was open before the install, or the install folder is not on PATHOpen a new window; see the documentation's PATH section
"! Needs authentication" in claude mcp listRegistered but not signed inStart a session, run /mcp, sign in
"✘ Failed to connect" for a local serverThe start command failsRun the part after -- by itself in the terminal and read the error
"⏸ Pending approval"A project server nobody approved on this machineRun claude in the project and approve it
The server's own flags are rejectedThe -- is missingPut -- before the server command
The server works in one project, not anotherIt was added at local scopeAdd it again with --scope user
A plugin's commands do not appearThe session loaded before the install/reload-plugins, or check the Errors tab in /plugin
Hooks with paths misbehave on WindowsPaths arrive with backslashesSee the tested hooks guide

12. What you can do now

  • Tell a plugin from an MCP server and know which command family manages each.
  • Add a remote server, sign in through /mcp, and add a local server with the double dash in the right place.
  • Pick local, project or user scope on purpose, and keep secrets out of .mcp.json.
  • Install, inspect, update and remove plugins, and add a marketplace from GitHub or a folder.

Every server and plugin adds tool descriptions that the model reads on each request, so install what you use and remove what you do not. For the project files that sit beside these, see Claude Code project setup.

Sources

This article reflects public information available when it was written. Versions, defaults and prices can change; check the linked official documentation.

Every command shown with output was run for this article with Claude Code 2.1.322 on Linux, in an empty test profile; the output is copied as printed, with folder names shortened. The macOS and Windows steps follow Anthropic's documentation as read on November 12, 2026 and were not run on those systems. No sign-in to a remote service was performed, so the OAuth step is described from the documentation. Written for this site with AI assistance, from the sources above. For errors or additional information, please request a correction. Editorial policy