add-mcp 1.5.1 → 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 +189 -76
- package/dist/index.js +791 -80
- 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
|
|
@@ -43,6 +120,9 @@ npx add-mcp "npx -y @org/mcp-server --flag value"
|
|
|
43
120
|
# Node.js script
|
|
44
121
|
npx add-mcp "node /path/to/server.js --port 3000"
|
|
45
122
|
|
|
123
|
+
# Local stdio server with environment variables (repeatable)
|
|
124
|
+
npx add-mcp @modelcontextprotocol/server-filesystem --env "API_KEY=secret" --env "DATABASE_URL=postgres://localhost/app"
|
|
125
|
+
|
|
46
126
|
# Install for Cursor and Claude Code
|
|
47
127
|
npx add-mcp https://mcp.example.com/mcp -a cursor -a claude-code
|
|
48
128
|
|
|
@@ -68,116 +148,149 @@ npx add-mcp https://mcp.example.com/mcp -a cursor -y --gitignore
|
|
|
68
148
|
| `-t, --transport <type>` | Transport type for remote servers: `http` (default), `sse` |
|
|
69
149
|
| `--type <type>` | Alias for `--transport` |
|
|
70
150
|
| `--header <header>` | HTTP header for remote servers (repeatable, `Key: Value`) |
|
|
151
|
+
| `--env <env>` | Env var for local stdio servers (repeatable, `KEY=VALUE`) |
|
|
71
152
|
| `-n, --name <name>` | Server name (auto-inferred if not provided) |
|
|
72
153
|
| `-y, --yes` | Skip all confirmation prompts |
|
|
73
154
|
| `--all` | Install to all agents |
|
|
74
155
|
| `--gitignore` | Add generated config files to `.gitignore` |
|
|
75
156
|
|
|
76
|
-
###
|
|
157
|
+
### Transport Types
|
|
77
158
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
| Command | Description |
|
|
81
|
-
| ------------- | ------------------------------------------------------------ |
|
|
82
|
-
| `list-agents` | List all supported coding agents with scope (project/global) |
|
|
83
|
-
|
|
84
|
-
```bash
|
|
85
|
-
# List all supported agents
|
|
86
|
-
npx add-mcp list-agents
|
|
87
|
-
```
|
|
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:
|
|
88
160
|
|
|
89
|
-
|
|
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) |
|
|
90
165
|
|
|
91
|
-
|
|
92
|
-
| ----------- | --------- | ----------------------- | --------------------------------------------- |
|
|
93
|
-
| **Project** | (default) | `.cursor/mcp.json` etc. | Committed with your project, shared with team |
|
|
94
|
-
| **Global** | `-g` | `~/.cursor/mcp.json` | Available across all projects |
|
|
166
|
+
Local servers (npm packages, commands) always use **stdio** transport.
|
|
95
167
|
|
|
96
|
-
|
|
168
|
+
Note that most agents like Cursor and opencode do not require the `type` information to be set.
|
|
97
169
|
|
|
98
|
-
|
|
170
|
+
## Find Command
|
|
99
171
|
|
|
100
|
-
|
|
172
|
+
### Usage Examples
|
|
101
173
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
-
|
|
174
|
+
```bash
|
|
175
|
+
# Search for servers by keyword and choose one interactively
|
|
176
|
+
npx add-mcp find vercel
|
|
105
177
|
|
|
106
|
-
|
|
178
|
+
# Browse servers without a keyword
|
|
179
|
+
npx add-mcp find
|
|
107
180
|
|
|
108
|
-
|
|
109
|
-
-
|
|
110
|
-
- Shows detected agents plus all other supported agents for selection
|
|
181
|
+
# Use search alias (same as find)
|
|
182
|
+
npx add-mcp search notion
|
|
111
183
|
|
|
112
|
-
|
|
184
|
+
# Install a found server globally to a specific agent without prompts
|
|
185
|
+
npx add-mcp find neon -a claude-code -g -y
|
|
113
186
|
|
|
114
|
-
|
|
115
|
-
|
|
187
|
+
# Install to all agents and add generated project configs to .gitignore
|
|
188
|
+
npx add-mcp find github --all --gitignore
|
|
189
|
+
```
|
|
116
190
|
|
|
117
|
-
|
|
191
|
+
### Options
|
|
118
192
|
|
|
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
|
-
|
|
122
|
-
| --------- | ------------------ | ----------------------------------------------------- |
|
|
123
|
-
| **HTTP** | `--transport http` | Streamable HTTP (default) |
|
|
124
|
-
| **SSE** | `--transport sse` | Server-Sent Events (deprecated by MCP but still used) |
|
|
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.
|
|
125
203
|
|
|
126
|
-
|
|
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.
|
|
127
205
|
|
|
128
|
-
|
|
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
|
-
|
|
133
|
-
Header support is available for remote installs across all supported agents.
|
|
212
|
+
### Configuring Registries for Find / Search
|
|
134
213
|
|
|
135
|
-
|
|
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.
|
|
136
215
|
|
|
137
|
-
|
|
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
|
-
|
|
140
|
-
| ---------------------- | -------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
141
|
-
| Antigravity | `antigravity` | - | `~/.gemini/antigravity/mcp_config.json` |
|
|
142
|
-
| Cline VSCode Extension | `cline` | - | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
|
|
143
|
-
| Cline CLI | `cline-cli` | - | `~/.cline/data/settings/cline_mcp_settings.json` |
|
|
144
|
-
| Claude Code | `claude-code` | `.mcp.json` | `~/.claude.json` |
|
|
145
|
-
| Claude Desktop | `claude-desktop` | - | `~/Library/Application Support/Claude/claude_desktop_config.json` |
|
|
146
|
-
| Codex | `codex` | `.codex/config.toml` | `~/.codex/config.toml` |
|
|
147
|
-
| Cursor | `cursor` | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
|
|
148
|
-
| Gemini CLI | `gemini-cli` | `.gemini/settings.json` | `~/.gemini/settings.json` |
|
|
149
|
-
| Goose | `goose` | `.goose/config.yaml` | `~/.config/goose/config.yaml` |
|
|
150
|
-
| GitHub Copilot CLI | `github-copilot-cli` | `.vscode/mcp.json` | `~/.copilot/mcp-config.json` |
|
|
151
|
-
| MCPorter | `mcporter` | `config/mcporter.json` | `~/.mcporter/mcporter.json` (or existing `~/.mcporter/mcporter.jsonc`) |
|
|
152
|
-
| OpenCode | `opencode` | `opencode.json` | `~/.config/opencode/opencode.json` |
|
|
153
|
-
| VS Code | `vscode` | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json` |
|
|
154
|
-
| Zed | `zed` | `.zed/settings.json` | `~/Library/Application Support/Zed/settings.json` |
|
|
218
|
+
### Built-in Registries
|
|
155
219
|
|
|
156
|
-
|
|
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. |
|
|
157
224
|
|
|
158
|
-
|
|
225
|
+
### Missing A Server in add-mcp Curated Registry?
|
|
159
226
|
|
|
160
|
-
|
|
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.
|
|
161
228
|
|
|
162
|
-
|
|
229
|
+
### Editing or Removing Registries
|
|
163
230
|
|
|
164
|
-
-
|
|
165
|
-
- Connect to databases (PostgreSQL, MySQL, etc.)
|
|
166
|
-
- Provide file system access
|
|
167
|
-
- Offer specialized tools for your workflow
|
|
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:
|
|
168
232
|
|
|
169
|
-
|
|
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
|
+
```
|
|
170
248
|
|
|
171
|
-
|
|
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
|
+
```
|
|
172
282
|
|
|
173
|
-
|
|
174
|
-
- Check the agent's MCP configuration file for syntax errors
|
|
175
|
-
- Ensure the server name doesn't conflict with existing servers
|
|
283
|
+
To add your own registry, append an entry to `findRegistries` in `~/.config/add-mcp/config.json`:
|
|
176
284
|
|
|
177
|
-
|
|
285
|
+
```json
|
|
286
|
+
{
|
|
287
|
+
"url": "https://my-registry.example.com/api/v1/servers",
|
|
288
|
+
"label": "My custom registry"
|
|
289
|
+
}
|
|
290
|
+
```
|
|
178
291
|
|
|
179
|
-
|
|
292
|
+
## Troubleshooting
|
|
180
293
|
|
|
181
|
-
|
|
294
|
+
### Server not loading
|
|
182
295
|
|
|
183
|
-
|
|
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.
|