Claude MCP Manager

A command-line tool for macOS to define, manage, and switch between different sets of mcpServers configurations (profiles) for the Claude Desktop application.

Goal

The Claude desktop app stores its configuration, including the mcpServers endpoints, in a JSON file at ~/Library/Application Support/Claude/claude_desktop_config.json. This tool allows you to define individual server configurations and group them into named profiles (e.g., 'default', 'work', 'experimental'). Activating a profile updates the mcpServers block in the main Claude config file with the servers defined in that profile, automatically restarting Claude to apply the changes. By separating server definitions and utilizing environment variables for secrets (see "How it Works"), you can easily share server configurations or commit profiles to version control without exposing sensitive credentials.

Quick Install (Recommended)

Run the following command in your macOS terminal:

curl -fsSL https://raw.githubusercontent.com/BLTGV/claude-mcp-manager/main/install.sh | sh

This downloads and executes the installer script, which handles dependency checks, copying files, and setting up the command-line tool.

Requirements

• macOS: The script relies on macOS-specific paths and commands (pgrep, kill, open). It will not work on Windows or Linux.
• jq: The script uses jq for JSON processing. Install via Homebrew: brew install jq.
• bash: Requires a reasonably modern version of bash (>= 3.2) for features like regex matching (=~). Standard macOS bash is sufficient.

Installation

Manual Installation

1. Clone the repository or download the source code.

2. Navigate to the project directory in your terminal.

3. Make the installer executable: chmod +x install.sh

4. Run the installer:

./install.sh

• The script will attempt to install to /usr/local/lib/claude-mcp-manager and create a symlink in /usr/local/bin. This might require sudo if you don't have write permissions.
• If /usr/local is not writable, it will fall back to $HOME/.local/lib and $HOME/.local/bin.
• The installer will notify you if the chosen bin directory is not in your $PATH and provide instructions to add it.

How it Works

• Configuration Directory: Stores all data in ~/.config/claude/.
• Servers Directory: Individual server definitions are stored as .json files in ~/.config/claude/servers/.
• Profiles Directory: Profiles, which contain lists of server names, are stored as .json files in ~/.config/claude/profiles/.
• Each profile file looks like: {\"servers\": [\"server1_name\", \"server2_name\"]}
• Target File: The script modifies the mcpServers key within the official Claude config file: ~/Library/Application Support/Claude/claude_desktop_config.json.
• **Secrets (.env file):** You can store sensitive values (like API keys) in ~/.config/claude/.env. Server definition files can reference these using placeholders like {{ENV:YOUR_API_KEY}} or {{DOTENV:YOUR_API_KEY}}. These are resolved when a profile is activated.
• **Tracking (loaded file):** The script keeps track of the *name* of the currently active profile in ~/.config/claude/loaded.
• **Backup (last.json):** Before applying a new profile, the script saves the *current* mcpServers block from the target file into ~/.config/claude/last.json, allowing easy rollback using the last command.
• First Run: The installer runs claude-mcp-manager server list to ensure the config directories are created upon successful installation.

Usage

claude-mcp-manager

Primary Commands

• `: Activate the specified profile. Reads server definitions listed in the profile, resolves secrets, constructs the mcpServers` block, backs up the current block in the main config, writes the new block, and restarts Claude.
• last: Restore the mcpServers block that was active before the last profile activation (from last.json) and restart Claude.
• server : Manage server definitions. Run claude-mcp-manager server help for details.
• profile : Manage profiles. Run claude-mcp-manager profile help for details.

Server Subcommands (claude-mcp-manager server ...)

• list: List available server definition files found in ~/.config/claude/servers/.
• show : Display the JSON content of the specified server definition file.
• add --file : Add a new server definition by copying the content from ``.
• add --json '{\"key\":\"value\"}': Add a new server definition using the provided JSON string.
• edit : Open the specified server definition file in your $EDITOR (or default like vim/nano).
• remove : Delete the specified server definition file (prompts for confirmation).
• extract [--profile ]: Read the mcpServers block from the main Claude config, save each server as a separate file in ~/.config/claude/servers/. Optionally, create or update the specified profile `` to list all extracted servers.

Profile Subcommands (claude-mcp-manager profile ...)

• list: List available profile files found in ~/.config/claude/profiles/.
• show : List the server names contained within the specified profile file and indicate if the corresponding server definition file exists.
• create : Create a new, empty profile file.
• copy : Copy an existing profile file to a new name.
• edit : Open the specified profile file in your $EDITOR (or default like vim/nano) to manually edit the server list.
• add : Add one or more server names to the specified profile's "servers" array.
• remove : Remove one or more server names from the specified profile's "servers" array.
• delete : Delete the specified profile file (prompts for confirmation).

Options

• help, -h, --help: Show the main help message.
• version, -v: Show the script version.

Acknowledgements

This project was built utilizing claude-task-master, an AI-driven task management system by Eyal Toledano (@eyaltoledano) and Ralph Ecom (@RalphEcom), to define, manage, and implement the features described above.

Shell Completion (Optional)

Tab completion is available for Bash and Zsh shells.

First, ensure claude-mcp-manager is installed and accessible in your PATH.

Bash

1. **Install bash-completion@2:** If you haven't already, install the latest bash completion system using Homebrew:

brew install bash-completion@2

2. **Add to .bash_profile:** Follow the instructions printed by brew info bash-completion@2 to add the necessary line to your ~/.bash_profile (or ~/.bashrc). It usually looks like this:

# Add the following line (or similar) to ~/.bash_profile
    export BASH_COMPLETION_COMPAT_DIR="$(brew --prefix)/etc/bash_completion.d"
    [[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && . "$(brew --prefix)/etc/profile.d/bash_completion.sh"

3. Generate and Install Script: Run the following command to generate the completion script and place it in the correct directory:

# Determine the completion directory
    COMPLETION_DIR="$(brew --prefix)/etc/bash_completion.d"
    # Ensure the directory exists
    mkdir -p "$COMPLETION_DIR"
    # Generate the script
    claude-mcp-manager completion bash > "${COMPLETION_DIR}/claude-mcp-manager"

4. Reload Shell: Open a new terminal window or run source ~/.bash_profile.

Zsh

Zsh has built-in completion support.

1. **Ensure compinit:** Make sure your ~/.zshrc file includes autoload -U compinit && compinit somewhere (usually near the beginning or end).

2. Choose a Completion Directory: Zsh completions are typically stored in a directory listed in your $fpath variable. A common user-specific location is ~/.zsh/completion. Create it if it doesn't exist:

mkdir -p ~/.zsh/completion

3. **Add Directory to fpath:** Ensure this directory is added to your Zsh function path in your ~/.zshrc *before* calling compinit:

# Add near the top of ~/.zshrc
    fpath=(~/.zsh/completion $fpath)
    
    # ... other zsh config ...
    
    # Ensure compinit is loaded
    autoload -U compinit && compinit

4. Generate and Install Script: Run the following command to generate the completion script. Note the filename starts with an underscore (_):

claude-mcp-manager completion zsh > ~/.zsh/completion/_claude-mcp-manager

5. Reload Shell: Open a new terminal window or run source ~/.zshrc.

After installation, you should be able to use tab completion for commands, subcommands, profile names, and server names.

Uninstall

To uninstall, run the following command:

claude-mcp-manager uninstall

This will remove the script and the command symlink. It will ask for confirmation first.

To *also* remove the configuration directory (~/.config/claude), which contains all your profiles, server definitions, logs, and the .env file (potentially containing secrets), use:

claude-mcp-manager uninstall --remove-config

Warning: Removing the configuration directory is permanent and requires a separate confirmation.