mcp-add

A CLI tool to easily add Model Context Protocol (MCP) servers to various AI coding clients.

Features

- Interactive, semi-interactive, and non-interactive modes
- Support for local (stdio) and remote (SSE/HTTP) MCP servers
- Configure multiple clients at once
- Global and project-level configuration scopes

Supported Clients

| Client | Global Config | Project Config |
| -------------- | ------------------------------------------------------------------------- | ----------------------- |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | - |
| Claude Code | ~/.claude.json | .mcp.json |
| Cursor | ~/.cursor/mcp.json | .cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | .windsurf/mcp.json |
| VS Code | ~/.vscode/mcp.json | .vscode/mcp.json |
| OpenCode | ~/.config/opencode/opencode.json | opencode.json |
| Continue | ~/.continue/config.yaml | .continue/config.yaml |
| Goose | ~/.config/goose/config.yaml | - |
| Codex | ~/.codex/config.yaml | - |
| Gemini CLI | ~/.gemini/settings.json | .gemini/settings.json |

Installation

``bash


Using npm

npm install -g mcp-add

Using pnpm

pnpm add -g mcp-add

Using yarn

yarn global add mcp-add
`

Or run directly with npx:

`bash
npx mcp-add
`

Usage

$3

Simply run mcp-add without arguments to enter interactive mode:

`bash
mcp-add
`

You'll be prompted for:

1. Server name
2. Server type (local or remote)
3. Command (for local) or URL (for remote)
4. Environment variables or headers
5. Configuration scope (global or project)
6. Which clients to configure

$3

Provide some arguments via command line and let the tool prompt for the rest:

`bash


Provide name and type, prompt for the rest

mcp-add --name my-server --type local

Provide everything except clients selection

mcp-add \
--name filesystem \
--type local \
--command "npx -y @modelcontextprotocol/server-filesystem /tmp" \
--scope global

Provide name and let the tool ask for everything else

mcp-add -n my-server
`

This is useful when you want to quickly specify known values but interactively choose from options like client selection.

$3

Provide all required arguments via command line flags for fully automated usage:

`bash


Local server example

mcp-add \
--name my-server \
--type local \
--command "npx -y @modelcontextprotocol/server-filesystem /tmp" \
--scope global \
--clients "claude,cursor,vscode"

Remote server example

mcp-add \
--name my-remote-server \
--type remote \
--url "https://mcp.example.com/sse" \
--headers "Authorization=Bearer token123" \
--scope project \
--clients "claude code,opencode"
`

Required flags for non-interactive mode:

- --name, --type, --scope, --clients
- --command (for local servers) or --url (for remote servers)

$3

| Option | Alias | Description |
| ----------- | ----- | ------------------------------------------------ |
| --name | -n | Server name (alphanumeric, hyphens, underscores) |
| --type | -t | Server type: local or remote |
| --command | -c | Full command to run (local servers only) |
| --env | -e | Environment variables as KEY=value,KEY2=value2 |
| --url | -u | Server URL (remote servers only) |
| --headers | -H | HTTP headers as Key=value,Key2=value2 |
| --scope | -s | Config scope: global or project |
| --clients | -C | Comma-separated list of clients |
| --help | -h | Show help |
| --version | -v | Show version |

Examples

$3

`bash
mcp-add \
--name filesystem \
--type local \
--command "npx -y @modelcontextprotocol/server-filesystem /home/user/documents" \
--scope global \
--clients claude
`

$3

`bash
mcp-add \
--name github \
--type local \
--command "npx -y @modelcontextprotocol/server-github" \
--env "GITHUB_TOKEN=ghp_xxxxxxxxxxxx" \
--scope global \
--clients "claude,claude code,cursor"
`

$3

`bash
mcp-add \
--name my-api \
--type remote \
--url "https://api.example.com/mcp" \
--headers "Authorization=Bearer secret,X-Custom-Header=value" \
--scope project \
--clients "vscode,cursor"
`

$3

`bash
mcp-add \
--name memory \
--type local \
--command "npx -y @modelcontextprotocol/server-memory" \
--scope global \
--clients "claude,claude code,cursor,windsurf,vscode,opencode"
`

Development

`bash


Clone the repository

git clone https://github.com/paoloricciuti/mcp-add.git
cd mcp-add

Install dependencies

pnpm install

Run locally

pnpm start

Type check

pnpm run check

Lint

pnpm run lint

Format

pnpm run format
``

License

MIT