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

# 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:

npx mcp-add

Usage

Interactive Mode

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

mcp-add

You'll be prompted for:

1. Server name
2. Server type (stdio, http, or sse)
3. Command (for stdio) or URL (for remote)
4. Environment variables or headers
5. Configuration scope (global or project)
6. Which clients to configure
7. OAuth client credentials when a selected remote client needs static registration

Semi-Interactive Mode

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

# Provide name and type, prompt for the rest
mcp-add --name my-server --type stdio

# Provide everything except clients selection
mcp-add \
  --name filesystem \
  --type stdio \
  --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.

Adding a -c or -u will automatically infer the type.

Non-Interactive Mode

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

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

# Remote server example
mcp-add \
  --name my-remote-server \
  --type http \
  --url "https://mcp.example.com/mcp" \
  --client-id "your-static-client-id" \
  --client-secret "your-static-client-secret" \
  --headers "Authorization=Bearer token123" \
  --scope project \
  --clients "claude code,cursor"

Required flags for non-interactive mode:

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

Command Line Options

| Option | Alias | Description | | ----------------- | ----- | ------------------------------------------------------- | | --name | -n | Server name (alphanumeric, hyphens, underscores) | | --type | -t | Server type: stdio, http, or sse | | --command | -c | Full command to run (stdio 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 | | --client-id | - | Static OAuth client ID for supported remote clients | | --client-secret | - | Static OAuth client secret for supported remote clients | | --scope | -s | Config scope: global or project | | --clients | -C | Comma-separated list of clients | | --help | -h | Show help | | --version | -v | Show version |

--client-id and --client-secret are currently applied only to remote claude code and cursor configurations.

Examples

Add a filesystem MCP server to Claude Desktop

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

Add a GitHub MCP server with environment variables

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

Add a remote MCP server to a project

mcp-add \
  --name my-api \
  --type http \
  --url "https://api.example.com/mcp" \
  --client-id "cdf3737dff9d485485968e50b63fd8b4" \
  --client-secret "super-secret-value" \
  --headers "Authorization=Bearer secret,X-Custom-Header=value" \
  --scope project \
  --clients "claude code,cursor"

Configure multiple clients at once

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

Development

# 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