add-mcp 1.6.0 → 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +249 -75
- package/dist/index.js +1389 -76
- package/package.json +7 -4
package/README.md
CHANGED
|
@@ -6,16 +6,97 @@ Supports **Claude Code**, **Codex**, **Cursor**, **OpenCode**, **VSCode** and [9
|
|
|
6
6
|
|
|
7
7
|
## Install an MCP Server
|
|
8
8
|
|
|
9
|
+
Install an MCP server by remote URL or package name:
|
|
10
|
+
|
|
9
11
|
```bash
|
|
10
12
|
npx add-mcp url | package name [options]
|
|
11
13
|
```
|
|
12
14
|
|
|
13
|
-
Example installing the Context7 MCP server:
|
|
15
|
+
Example installing the Context7 remote MCP server:
|
|
14
16
|
|
|
15
17
|
```bash
|
|
16
18
|
npx add-mcp https://mcp.context7.com/mcp
|
|
17
19
|
```
|
|
18
20
|
|
|
21
|
+
You can add env variables and arguments (stdio) and headers (remote) to the server config using the `--env`, `--args` and `--header` options.
|
|
22
|
+
|
|
23
|
+
## Find an MCP Servers
|
|
24
|
+
|
|
25
|
+
Find and install MCP servers from the add-mcp curated registry and/or the official Anthropic MCP registry:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npx add-mcp find vercel
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
When running `find`/`search` for the first time, the CLI prompts you to choose which registries to enable (add-mcp curated registry and/or official Anthropic registry). You can also add custom registries to the configuration file.
|
|
32
|
+
|
|
33
|
+
## Supported Agents
|
|
34
|
+
|
|
35
|
+
MCP servers can be installed to any of these agents:
|
|
36
|
+
|
|
37
|
+
| Agent | `--agent` | Project Path | Global Path |
|
|
38
|
+
| ---------------------- | -------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
39
|
+
| Antigravity | `antigravity` | - | `~/.gemini/antigravity/mcp_config.json` |
|
|
40
|
+
| Cline VSCode Extension | `cline` | - | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
|
|
41
|
+
| Cline CLI | `cline-cli` | - | `~/.cline/data/settings/cline_mcp_settings.json` |
|
|
42
|
+
| Claude Code | `claude-code` | `.mcp.json` | `~/.claude.json` |
|
|
43
|
+
| Claude Desktop | `claude-desktop` | - | `~/Library/Application Support/Claude/claude_desktop_config.json` |
|
|
44
|
+
| Codex | `codex` | `.codex/config.toml` | `~/.codex/config.toml` |
|
|
45
|
+
| Cursor | `cursor` | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
|
|
46
|
+
| Gemini CLI | `gemini-cli` | `.gemini/settings.json` | `~/.gemini/settings.json` |
|
|
47
|
+
| Goose | `goose` | `.goose/config.yaml` | `~/.config/goose/config.yaml` |
|
|
48
|
+
| GitHub Copilot CLI | `github-copilot-cli` | `.vscode/mcp.json` | `~/.copilot/mcp-config.json` |
|
|
49
|
+
| MCPorter | `mcporter` | `config/mcporter.json` | `~/.mcporter/mcporter.json` (or existing `~/.mcporter/mcporter.jsonc`) |
|
|
50
|
+
| OpenCode | `opencode` | `opencode.json` | `~/.config/opencode/opencode.json` |
|
|
51
|
+
| VS Code | `vscode` | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json` |
|
|
52
|
+
| Zed | `zed` | `.zed/settings.json` | `~/Library/Application Support/Zed/settings.json` |
|
|
53
|
+
|
|
54
|
+
**Aliases:** `cline-vscode` → `cline`, `gemini` → `gemini-cli`, `github-copilot` → `vscode`
|
|
55
|
+
|
|
56
|
+
## Installation Scope
|
|
57
|
+
|
|
58
|
+
| Scope | Flag | Location | Use Case |
|
|
59
|
+
| ----------- | --------- | ----------------------- | --------------------------------------------- |
|
|
60
|
+
| **Project** | (default) | `.cursor/mcp.json` etc. | Committed with your project, shared with team |
|
|
61
|
+
| **Global** | `-g` | `~/.cursor/mcp.json` | Available across all projects |
|
|
62
|
+
|
|
63
|
+
## Smart Detection
|
|
64
|
+
|
|
65
|
+
The CLI automatically detects agents based on your environment:
|
|
66
|
+
|
|
67
|
+
**Default (project mode):**
|
|
68
|
+
|
|
69
|
+
- Detects project-level config files (`.cursor/`, `.vscode/`, `.mcp.json`, etc.)
|
|
70
|
+
- Selects detected agents (have project config in the current directory) by default
|
|
71
|
+
- Shows detected agents plus all other supported agents for selection
|
|
72
|
+
|
|
73
|
+
**With `-g` (global mode):**
|
|
74
|
+
|
|
75
|
+
- Detects all globally-installed agents (including Claude Desktop, Codex, Zed)
|
|
76
|
+
- Selects detected agents by default
|
|
77
|
+
- Shows detected agents plus all other supported agents for selection
|
|
78
|
+
|
|
79
|
+
**No agents detected:**
|
|
80
|
+
|
|
81
|
+
- Interactive mode: Defaults to the last selection and shows all agents for selection
|
|
82
|
+
- With `--yes`: Installs to all project-capable agents (project mode) or all global-capable agents (global mode)
|
|
83
|
+
|
|
84
|
+
## Commands
|
|
85
|
+
|
|
86
|
+
Besides the implicit add command, `add-mcp` also supports the following commands:
|
|
87
|
+
|
|
88
|
+
| Command | Description |
|
|
89
|
+
| ------------- | ------------------------------------------------------------ |
|
|
90
|
+
| `find` | Search MCP registry servers and install a selected match |
|
|
91
|
+
| `search` | Alias for `find` |
|
|
92
|
+
| `list` | List installed MCP servers across detected agents |
|
|
93
|
+
| `remove` | Remove an MCP server from agent configurations |
|
|
94
|
+
| `sync` | Synchronize server names and installations across agents |
|
|
95
|
+
| `unify` | Alias for `sync` |
|
|
96
|
+
| `list-agents` | List all supported coding agents with scope (project/global) |
|
|
97
|
+
|
|
98
|
+
## Add Command
|
|
99
|
+
|
|
19
100
|
### Usage Examples
|
|
20
101
|
|
|
21
102
|
```bash
|
|
@@ -77,116 +158,209 @@ npx add-mcp https://mcp.example.com/mcp -a cursor -y --gitignore
|
|
|
77
158
|
| `--all` | Install to all agents |
|
|
78
159
|
| `--gitignore` | Add generated config files to `.gitignore` |
|
|
79
160
|
|
|
80
|
-
###
|
|
161
|
+
### Transport Types
|
|
81
162
|
|
|
82
|
-
|
|
163
|
+
`add-mcp` supports all three transport types: HTTP, SSE, and stdio. Some agents require `type` option to be set to specify the transport type. You can use the `--type` or `--transport` option to specify the transport type:
|
|
83
164
|
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
|
|
|
165
|
+
| Transport | Flag | Description |
|
|
166
|
+
| --------- | ------------------ | ----------------------------------------------------- |
|
|
167
|
+
| **HTTP** | `--transport http` | Streamable HTTP (default) |
|
|
168
|
+
| **SSE** | `--transport sse` | Server-Sent Events (deprecated by MCP but still used) |
|
|
169
|
+
|
|
170
|
+
Local servers (npm packages, commands) always use **stdio** transport.
|
|
171
|
+
|
|
172
|
+
Note that most agents like Cursor and opencode do not require the `type` information to be set.
|
|
173
|
+
|
|
174
|
+
## Find Command
|
|
175
|
+
|
|
176
|
+
### Usage Examples
|
|
87
177
|
|
|
88
178
|
```bash
|
|
89
|
-
#
|
|
90
|
-
npx add-mcp
|
|
179
|
+
# Search for servers by keyword and choose one interactively
|
|
180
|
+
npx add-mcp find vercel
|
|
181
|
+
|
|
182
|
+
# Browse servers without a keyword
|
|
183
|
+
npx add-mcp find
|
|
184
|
+
|
|
185
|
+
# Use search alias (same as find)
|
|
186
|
+
npx add-mcp search notion
|
|
187
|
+
|
|
188
|
+
# Install a found server globally to a specific agent without prompts
|
|
189
|
+
npx add-mcp find neon -a claude-code -g -y
|
|
190
|
+
|
|
191
|
+
# Install to all agents and add generated project configs to .gitignore
|
|
192
|
+
npx add-mcp find github --all --gitignore
|
|
91
193
|
```
|
|
92
194
|
|
|
93
|
-
###
|
|
195
|
+
### Options
|
|
94
196
|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
197
|
+
| Option | Description |
|
|
198
|
+
| --------------------- | ------------------------------------------------------------------------ |
|
|
199
|
+
| `-g, --global` | Install to user directory instead of project |
|
|
200
|
+
| `-a, --agent <agent>` | Target specific agents (e.g., `cursor`, `claude-code`). Can be repeated. |
|
|
201
|
+
| `-n, --name <name>` | Server name override (defaults to the selected catalog entry name) |
|
|
202
|
+
| `-y, --yes` | Skip confirmation prompts |
|
|
203
|
+
| `--all` | Install to all agents |
|
|
204
|
+
| `--gitignore` | Add generated config files to `.gitignore` |
|
|
99
205
|
|
|
100
|
-
|
|
206
|
+
Transport for `find`/`search` is inferred from registry metadata. The CLI prefers HTTP remotes when available and only falls back to SSE when HTTP is not available for the selected install context.
|
|
101
207
|
|
|
102
|
-
|
|
208
|
+
When a server offers both remote and stdio package options, interactive mode lets you choose one (remote is the default). With `-y`, it auto-selects remote.
|
|
103
209
|
|
|
104
|
-
|
|
210
|
+
If a selected remote server defines URL variables or header inputs:
|
|
105
211
|
|
|
106
|
-
-
|
|
107
|
-
-
|
|
108
|
-
-
|
|
212
|
+
- required values must be provided
|
|
213
|
+
- optional values can be skipped with Enter
|
|
214
|
+
- with `-y`, placeholders are inserted (for example `<your-header-value-here>`)
|
|
109
215
|
|
|
110
|
-
|
|
216
|
+
### Configuring Registries for Find / Search
|
|
111
217
|
|
|
112
|
-
|
|
113
|
-
- Selects detected agents by default
|
|
114
|
-
- Shows detected agents plus all other supported agents for selection
|
|
218
|
+
The first time you run `find` or `search`, the CLI prompts you to choose which registries to enable. Your selection is saved to `~/.config/add-mcp/config.json` (respects `XDG_CONFIG_HOME`) and reused on every subsequent search.
|
|
115
219
|
|
|
116
|
-
|
|
220
|
+
If you run with `-y` before this one-time registry setup is completed, the CLI exits with guidance to rerun without `--yes`.
|
|
117
221
|
|
|
118
|
-
-
|
|
119
|
-
- With `--yes`: Installs to all project-capable agents (project mode) or all global-capable agents (global mode)
|
|
222
|
+
### Built-in Registries
|
|
120
223
|
|
|
121
|
-
|
|
224
|
+
| Registry | Base URL | Description |
|
|
225
|
+
| ------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
226
|
+
| **add-mcp curated registry** | `https://mcp.agent-tooling.dev/api/v1/servers` | A curated list of first-party, verified MCP servers from popular developer tools and SaaS services. Designed to surface high-quality, officially maintained servers instead of a long tail of unmaintained or third-party entries. |
|
|
227
|
+
| **Official Anthropic registry** | `https://registry.modelcontextprotocol.io/v0.1/servers` | The community-driven MCP server registry maintained by Anthropic. Contains the broadest catalog of MCP servers. |
|
|
122
228
|
|
|
123
|
-
|
|
229
|
+
### Missing A Server in add-mcp Curated Registry?
|
|
124
230
|
|
|
125
|
-
|
|
126
|
-
| --------- | ------------------ | ----------------------------------------------------- |
|
|
127
|
-
| **HTTP** | `--transport http` | Streamable HTTP (default) |
|
|
128
|
-
| **SSE** | `--transport sse` | Server-Sent Events (deprecated by MCP but still used) |
|
|
231
|
+
The source of truth for the add-mcp curated registry is [registry.json](registry.json) in this repository. You can contribute to the registry by opening a pull request to add or update a server.
|
|
129
232
|
|
|
130
|
-
|
|
233
|
+
### Editing or Removing Registries
|
|
131
234
|
|
|
132
|
-
|
|
235
|
+
Registry selections are stored in `~/.config/add-mcp/config.json` under the `findRegistries` key. You can edit this file directly to add, remove, or reorder registries:
|
|
133
236
|
|
|
134
|
-
|
|
237
|
+
```json
|
|
238
|
+
{
|
|
239
|
+
"version": 1,
|
|
240
|
+
"findRegistries": [
|
|
241
|
+
{
|
|
242
|
+
"url": "https://mcp.agent-tooling.dev/api/v1/servers",
|
|
243
|
+
"label": "add-mcp curated registry"
|
|
244
|
+
},
|
|
245
|
+
{
|
|
246
|
+
"url": "https://registry.modelcontextprotocol.io/v0.1/servers",
|
|
247
|
+
"label": "Official Anthropic registry"
|
|
248
|
+
}
|
|
249
|
+
]
|
|
250
|
+
}
|
|
251
|
+
```
|
|
135
252
|
|
|
136
|
-
|
|
137
|
-
|
|
253
|
+
To reset and re-trigger the interactive selection prompt, remove the `findRegistries` key (or delete the file entirely).
|
|
254
|
+
|
|
255
|
+
### Adding a Custom Registry
|
|
256
|
+
|
|
257
|
+
Any server that implements the registry API can be added as a custom entry. The CLI sends a `GET` request to the configured `url` with the following query parameters:
|
|
258
|
+
|
|
259
|
+
| Parameter | Value |
|
|
260
|
+
| --------- | -------------------------------------- |
|
|
261
|
+
| `search` | The user's search keyword (lowercased) |
|
|
262
|
+
| `version` | `latest` |
|
|
263
|
+
| `limit` | `100` |
|
|
264
|
+
|
|
265
|
+
The endpoint must return JSON in this shape:
|
|
266
|
+
|
|
267
|
+
```json
|
|
268
|
+
{
|
|
269
|
+
"servers": [
|
|
270
|
+
{
|
|
271
|
+
"server": {
|
|
272
|
+
"name": "example-server",
|
|
273
|
+
"description": "An example MCP server",
|
|
274
|
+
"version": "1.0.0",
|
|
275
|
+
"remotes": [
|
|
276
|
+
{
|
|
277
|
+
"type": "streamable-http",
|
|
278
|
+
"url": "https://mcp.example.com/mcp"
|
|
279
|
+
}
|
|
280
|
+
]
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
]
|
|
284
|
+
}
|
|
285
|
+
```
|
|
138
286
|
|
|
139
|
-
|
|
287
|
+
To add your own registry, append an entry to `findRegistries` in `~/.config/add-mcp/config.json`:
|
|
140
288
|
|
|
141
|
-
|
|
142
|
-
|
|
289
|
+
```json
|
|
290
|
+
{
|
|
291
|
+
"url": "https://my-registry.example.com/api/v1/servers",
|
|
292
|
+
"label": "My custom registry"
|
|
293
|
+
}
|
|
294
|
+
```
|
|
143
295
|
|
|
144
|
-
##
|
|
296
|
+
## List Command
|
|
145
297
|
|
|
146
|
-
|
|
298
|
+
List installed MCP servers across detected agents:
|
|
147
299
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
| Cline VSCode Extension | `cline` | - | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
|
|
152
|
-
| Cline CLI | `cline-cli` | - | `~/.cline/data/settings/cline_mcp_settings.json` |
|
|
153
|
-
| Claude Code | `claude-code` | `.mcp.json` | `~/.claude.json` |
|
|
154
|
-
| Claude Desktop | `claude-desktop` | - | `~/Library/Application Support/Claude/claude_desktop_config.json` |
|
|
155
|
-
| Codex | `codex` | `.codex/config.toml` | `~/.codex/config.toml` |
|
|
156
|
-
| Cursor | `cursor` | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
|
|
157
|
-
| Gemini CLI | `gemini-cli` | `.gemini/settings.json` | `~/.gemini/settings.json` |
|
|
158
|
-
| Goose | `goose` | `.goose/config.yaml` | `~/.config/goose/config.yaml` |
|
|
159
|
-
| GitHub Copilot CLI | `github-copilot-cli` | `.vscode/mcp.json` | `~/.copilot/mcp-config.json` |
|
|
160
|
-
| MCPorter | `mcporter` | `config/mcporter.json` | `~/.mcporter/mcporter.json` (or existing `~/.mcporter/mcporter.jsonc`) |
|
|
161
|
-
| OpenCode | `opencode` | `opencode.json` | `~/.config/opencode/opencode.json` |
|
|
162
|
-
| VS Code | `vscode` | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json` |
|
|
163
|
-
| Zed | `zed` | `.zed/settings.json` | `~/Library/Application Support/Zed/settings.json` |
|
|
300
|
+
```bash
|
|
301
|
+
# List servers for all detected agents in the project
|
|
302
|
+
npx add-mcp list
|
|
164
303
|
|
|
165
|
-
|
|
304
|
+
# List global server configs
|
|
305
|
+
npx add-mcp list -g
|
|
166
306
|
|
|
167
|
-
|
|
307
|
+
# List servers for a specific agent (shown even if not detected)
|
|
308
|
+
npx add-mcp list -a cursor
|
|
309
|
+
```
|
|
168
310
|
|
|
169
|
-
|
|
311
|
+
| Option | Description |
|
|
312
|
+
| --------------------- | -------------------------------------- |
|
|
313
|
+
| `-g, --global` | List global configs instead of project |
|
|
314
|
+
| `-a, --agent <agent>` | Filter to specific agent(s) |
|
|
170
315
|
|
|
171
|
-
|
|
316
|
+
## Remove Command
|
|
172
317
|
|
|
173
|
-
|
|
174
|
-
- Connect to databases (PostgreSQL, MySQL, etc.)
|
|
175
|
-
- Provide file system access
|
|
176
|
-
- Offer specialized tools for your workflow
|
|
318
|
+
Remove an MCP server from agent configurations by server name, URL, or package name:
|
|
177
319
|
|
|
178
|
-
|
|
320
|
+
```bash
|
|
321
|
+
# Remove by server name (interactive selection by default)
|
|
322
|
+
npx add-mcp remove neon
|
|
179
323
|
|
|
180
|
-
|
|
324
|
+
# Remove all matches without prompting
|
|
325
|
+
npx add-mcp remove neon -y
|
|
326
|
+
|
|
327
|
+
# Remove by URL
|
|
328
|
+
npx add-mcp remove https://mcp.neon.tech/mcp -y
|
|
329
|
+
|
|
330
|
+
# Remove from global configs for a specific agent
|
|
331
|
+
npx add-mcp remove neon -g -a cursor -y
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
| Option | Description |
|
|
335
|
+
| --------------------- | ------------------------------------ |
|
|
336
|
+
| `-g, --global` | Remove from global configs |
|
|
337
|
+
| `-a, --agent <agent>` | Filter to specific agent(s) |
|
|
338
|
+
| `-y, --yes` | Remove all matches without prompting |
|
|
181
339
|
|
|
182
|
-
|
|
183
|
-
- Check the agent's MCP configuration file for syntax errors
|
|
184
|
-
- Ensure the server name doesn't conflict with existing servers
|
|
340
|
+
## Sync Command
|
|
185
341
|
|
|
186
|
-
|
|
342
|
+
Synchronize server names and installations across all detected agents. Servers are grouped by URL or package name, and each group is unified to the shortest server name. Servers with conflicting headers, env, or args across agents are skipped with a warning.
|
|
187
343
|
|
|
188
|
-
|
|
344
|
+
```bash
|
|
345
|
+
# Sync project-level configs (interactive confirmation)
|
|
346
|
+
npx add-mcp sync
|
|
347
|
+
|
|
348
|
+
# Sync without prompting
|
|
349
|
+
npx add-mcp sync -y
|
|
350
|
+
|
|
351
|
+
# Sync global configs
|
|
352
|
+
npx add-mcp sync -g -y
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
| Option | Description |
|
|
356
|
+
| -------------- | -------------------------------------- |
|
|
357
|
+
| `-g, --global` | Sync global configs instead of project |
|
|
358
|
+
| `-y, --yes` | Skip confirmation prompts |
|
|
189
359
|
|
|
190
|
-
|
|
360
|
+
`unify` is an alias for `sync`.
|
|
361
|
+
|
|
362
|
+
## Troubleshooting
|
|
363
|
+
|
|
364
|
+
### Server not loading
|
|
191
365
|
|
|
192
|
-
|
|
366
|
+
Some agents & editors like Claude Code require a restart to load the new MCP server. Otherwise, like Cursor, require you to navigate to the MCP settings page and toggle the new server as enabled.
|