Claude MCP Manager

What is 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. It is for users who want to organize multiple MCP server setups and easily activate them.

How to use Claude MCP Manager?

Install via the provided one-liner or manually, then run claude-mcp-manager <command | profile_name | option> in the terminal. Activate a profile by passing its name as the first argument; manage server definitions and profiles using the server and profile subcommands.

Key features of Claude MCP Manager

• Define individual MCP server configurations as separate JSON files.
• Group servers into named profiles (e.g., 'default', 'work', 'experimental').
• Activate a profile to update the Claude desktop config and restart the app.
• Use environment variables for secrets via a .env file with placeholders.
• Backup and restore previous mcpServers state with the last command.
• Extract existing servers from the active Claude config into defined files.

Use cases of Claude MCP Manager

• Quickly switch between development, testing, and production MCP server sets.
• Share server configurations across team members without exposing API keys.
• Keep a stable "default" profile and experiment with new servers in separate profiles.
• Recover from a broken configuration by rolling back to the last active profile.
• Manage and document all MCP servers used in different projects or workflows.

FAQ from Claude MCP Manager

What are the system requirements?

macOS is required (uses pgrep, kill, open). Also needs jq for JSON processing (install via brew install jq) and a modern bash (>= 3.2, standard on macOS).

Where does Claude MCP Manager store its data?

All data is stored in ~/.config/claude/. Server definitions go in servers/, profiles in profiles/, the active profile name in loaded, and a backup of the previous mcpServers block in last.json. The .env file for secrets is also kept there.

How are secrets managed?

Sensitive values like API keys are stored in ~/.config/claude/.env. Server definition files reference them with placeholders like {{ENV:YOUR_API_KEY}} or {{DOTENV:YOUR_API_KEY}}, which are resolved when a profile is activated.

Can I undo a profile activation?

Yes. Run claude-mcp-manager last to restore the mcpServers block that was active before the last profile activation (backed up to last.json). This restarts Claude automatically.

Does Claude MCP Manager provide shell completion?

Yes. Optional tab completion is available for Bash and Zsh. Generation and installation instructions are provided in the README.