add-mcp 1.6.0 → 1.7.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 +183 -79
- package/dist/index.js +739 -76
- package/package.json +7 -4
package/README.md
CHANGED
|
@@ -6,16 +6,93 @@ 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-agents` | List all supported coding agents with scope (project/global) |
|
|
93
|
+
|
|
94
|
+
## Add Command
|
|
95
|
+
|
|
19
96
|
### Usage Examples
|
|
20
97
|
|
|
21
98
|
```bash
|
|
@@ -77,116 +154,143 @@ npx add-mcp https://mcp.example.com/mcp -a cursor -y --gitignore
|
|
|
77
154
|
| `--all` | Install to all agents |
|
|
78
155
|
| `--gitignore` | Add generated config files to `.gitignore` |
|
|
79
156
|
|
|
80
|
-
###
|
|
157
|
+
### Transport Types
|
|
81
158
|
|
|
82
|
-
|
|
159
|
+
`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
160
|
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
|
|
|
161
|
+
| Transport | Flag | Description |
|
|
162
|
+
| --------- | ------------------ | ----------------------------------------------------- |
|
|
163
|
+
| **HTTP** | `--transport http` | Streamable HTTP (default) |
|
|
164
|
+
| **SSE** | `--transport sse` | Server-Sent Events (deprecated by MCP but still used) |
|
|
87
165
|
|
|
88
|
-
|
|
89
|
-
# List all supported agents
|
|
90
|
-
npx add-mcp list-agents
|
|
91
|
-
```
|
|
166
|
+
Local servers (npm packages, commands) always use **stdio** transport.
|
|
92
167
|
|
|
93
|
-
|
|
168
|
+
Note that most agents like Cursor and opencode do not require the `type` information to be set.
|
|
94
169
|
|
|
95
|
-
|
|
96
|
-
| ----------- | --------- | ----------------------- | --------------------------------------------- |
|
|
97
|
-
| **Project** | (default) | `.cursor/mcp.json` etc. | Committed with your project, shared with team |
|
|
98
|
-
| **Global** | `-g` | `~/.cursor/mcp.json` | Available across all projects |
|
|
170
|
+
## Find Command
|
|
99
171
|
|
|
100
|
-
###
|
|
172
|
+
### Usage Examples
|
|
101
173
|
|
|
102
|
-
|
|
174
|
+
```bash
|
|
175
|
+
# Search for servers by keyword and choose one interactively
|
|
176
|
+
npx add-mcp find vercel
|
|
103
177
|
|
|
104
|
-
|
|
178
|
+
# Browse servers without a keyword
|
|
179
|
+
npx add-mcp find
|
|
105
180
|
|
|
106
|
-
|
|
107
|
-
-
|
|
108
|
-
- Shows detected agents plus all other supported agents for selection
|
|
181
|
+
# Use search alias (same as find)
|
|
182
|
+
npx add-mcp search notion
|
|
109
183
|
|
|
110
|
-
|
|
184
|
+
# Install a found server globally to a specific agent without prompts
|
|
185
|
+
npx add-mcp find neon -a claude-code -g -y
|
|
111
186
|
|
|
112
|
-
|
|
113
|
-
-
|
|
114
|
-
|
|
187
|
+
# Install to all agents and add generated project configs to .gitignore
|
|
188
|
+
npx add-mcp find github --all --gitignore
|
|
189
|
+
```
|
|
115
190
|
|
|
116
|
-
|
|
191
|
+
### Options
|
|
117
192
|
|
|
118
|
-
|
|
119
|
-
|
|
193
|
+
| Option | Description |
|
|
194
|
+
| --------------------- | ------------------------------------------------------------------------ |
|
|
195
|
+
| `-g, --global` | Install to user directory instead of project |
|
|
196
|
+
| `-a, --agent <agent>` | Target specific agents (e.g., `cursor`, `claude-code`). Can be repeated. |
|
|
197
|
+
| `-n, --name <name>` | Server name override (defaults to the selected catalog entry name) |
|
|
198
|
+
| `-y, --yes` | Skip confirmation prompts |
|
|
199
|
+
| `--all` | Install to all agents |
|
|
200
|
+
| `--gitignore` | Add generated config files to `.gitignore` |
|
|
120
201
|
|
|
121
|
-
|
|
202
|
+
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.
|
|
122
203
|
|
|
123
|
-
|
|
204
|
+
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.
|
|
124
205
|
|
|
125
|
-
|
|
126
|
-
| --------- | ------------------ | ----------------------------------------------------- |
|
|
127
|
-
| **HTTP** | `--transport http` | Streamable HTTP (default) |
|
|
128
|
-
| **SSE** | `--transport sse` | Server-Sent Events (deprecated by MCP but still used) |
|
|
206
|
+
If a selected remote server defines URL variables or header inputs:
|
|
129
207
|
|
|
130
|
-
|
|
208
|
+
- required values must be provided
|
|
209
|
+
- optional values can be skipped with Enter
|
|
210
|
+
- with `-y`, placeholders are inserted (for example `<your-header-value-here>`)
|
|
131
211
|
|
|
132
|
-
|
|
212
|
+
### Configuring Registries for Find / Search
|
|
133
213
|
|
|
134
|
-
|
|
214
|
+
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.
|
|
135
215
|
|
|
136
|
-
|
|
137
|
-
Header support is available for remote installs across all supported agents.
|
|
216
|
+
If you run with `-y` before this one-time registry setup is completed, the CLI exits with guidance to rerun without `--yes`.
|
|
138
217
|
|
|
139
|
-
|
|
218
|
+
### Built-in Registries
|
|
140
219
|
|
|
141
|
-
|
|
142
|
-
|
|
220
|
+
| Registry | Base URL | Description |
|
|
221
|
+
| ------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
222
|
+
| **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. |
|
|
223
|
+
| **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. |
|
|
143
224
|
|
|
144
|
-
|
|
225
|
+
### Missing A Server in add-mcp Curated Registry?
|
|
145
226
|
|
|
146
|
-
|
|
227
|
+
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.
|
|
147
228
|
|
|
148
|
-
|
|
149
|
-
| ---------------------- | -------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
150
|
-
| Antigravity | `antigravity` | - | `~/.gemini/antigravity/mcp_config.json` |
|
|
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` |
|
|
229
|
+
### Editing or Removing Registries
|
|
164
230
|
|
|
165
|
-
|
|
231
|
+
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:
|
|
166
232
|
|
|
167
|
-
|
|
233
|
+
```json
|
|
234
|
+
{
|
|
235
|
+
"version": 1,
|
|
236
|
+
"findRegistries": [
|
|
237
|
+
{
|
|
238
|
+
"url": "https://mcp.agent-tooling.dev/api/v1/servers",
|
|
239
|
+
"label": "add-mcp curated registry"
|
|
240
|
+
},
|
|
241
|
+
{
|
|
242
|
+
"url": "https://registry.modelcontextprotocol.io/v0.1/servers",
|
|
243
|
+
"label": "Official Anthropic registry"
|
|
244
|
+
}
|
|
245
|
+
]
|
|
246
|
+
}
|
|
247
|
+
```
|
|
168
248
|
|
|
169
|
-
|
|
249
|
+
To reset and re-trigger the interactive selection prompt, remove the `findRegistries` key (or delete the file entirely).
|
|
250
|
+
|
|
251
|
+
### Adding a Custom Registry
|
|
252
|
+
|
|
253
|
+
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:
|
|
254
|
+
|
|
255
|
+
| Parameter | Value |
|
|
256
|
+
| --------- | -------------------------------------- |
|
|
257
|
+
| `search` | The user's search keyword (lowercased) |
|
|
258
|
+
| `version` | `latest` |
|
|
259
|
+
| `limit` | `100` |
|
|
260
|
+
|
|
261
|
+
The endpoint must return JSON in this shape:
|
|
262
|
+
|
|
263
|
+
```json
|
|
264
|
+
{
|
|
265
|
+
"servers": [
|
|
266
|
+
{
|
|
267
|
+
"server": {
|
|
268
|
+
"name": "example-server",
|
|
269
|
+
"description": "An example MCP server",
|
|
270
|
+
"version": "1.0.0",
|
|
271
|
+
"remotes": [
|
|
272
|
+
{
|
|
273
|
+
"type": "streamable-http",
|
|
274
|
+
"url": "https://mcp.example.com/mcp"
|
|
275
|
+
}
|
|
276
|
+
]
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
]
|
|
280
|
+
}
|
|
281
|
+
```
|
|
170
282
|
|
|
171
|
-
|
|
283
|
+
To add your own registry, append an entry to `findRegistries` in `~/.config/add-mcp/config.json`:
|
|
172
284
|
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
-
|
|
176
|
-
|
|
285
|
+
```json
|
|
286
|
+
{
|
|
287
|
+
"url": "https://my-registry.example.com/api/v1/servers",
|
|
288
|
+
"label": "My custom registry"
|
|
289
|
+
}
|
|
290
|
+
```
|
|
177
291
|
|
|
178
292
|
## Troubleshooting
|
|
179
293
|
|
|
180
294
|
### Server not loading
|
|
181
295
|
|
|
182
|
-
|
|
183
|
-
- Check the agent's MCP configuration file for syntax errors
|
|
184
|
-
- Ensure the server name doesn't conflict with existing servers
|
|
185
|
-
|
|
186
|
-
### Permission errors
|
|
187
|
-
|
|
188
|
-
Ensure you have write access to the target configuration directory.
|
|
189
|
-
|
|
190
|
-
## License
|
|
191
|
-
|
|
192
|
-
Apache 2.0
|
|
296
|
+
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.
|