ClaudeCode MCP Manager

A beautiful terminal UI for managing Model Context Protocol (MCP) servers in Claude Code.

⚠️ Development Status: This is an actively developed project that has been tested in limited environments. While the core functionality works, it may contain bugs or edge cases. Use with caution and always keep backups of your Claude configuration files.

Features

• 🎨 Beautiful TUI - Built with Bubble Tea for a smooth terminal experience
• 🔄 Toggle MCPs - Enable/disable MCPs instantly with a single keypress
• 👤 Profile Support - Manage different MCP sets for different Claude instances (e.g., glm vs claude)
• 💾 Auto-Backup - Automatic backups before every change with easy restore
• ⚡ Real-Time Status - See which MCPs are running, stopped, or failed
• 🎯 Simple Interface - Vim-style navigation, no manual needed

Installation

Recommended: Using Install Script

git clone https://github.com/donmecca/claudecode-mcp-manager
cd claudecode-mcp-manager

# Build and install to ~/.local/bin (no sudo needed)
./scripts/install.sh --build --local

# Or install to /usr/local/bin (requires sudo)
sudo ./scripts/install.sh --build

The install script automatically handles macOS Gatekeeper quarantine removal.

From Source (Manual)

git clone https://github.com/donmecca/claudecode-mcp-manager
cd claudecode-mcp-manager
go build -o mcp-manager

# Install to ~/.local/bin
cp mcp-manager ~/.local/bin/
chmod +x ~/.local/bin/mcp-manager

# On macOS: Remove Gatekeeper quarantine
xattr -d com.apple.quarantine ~/.local/bin/mcp-manager 2>/dev/null || true

# Or install to /usr/local/bin (requires sudo)
sudo mv mcp-manager /usr/local/bin/

Using Go Install

go install github.com/donmecca/claudecode-mcp-manager@latest

Quick Start

# Launch the TUI (default profile)
mcp-manager

# Launch with specific profile
mcp-manager --profile glm

# Or switch profiles from within the app:
# 1. Launch mcp-manager
# 2. Press 'p' to view profiles
# 3. Select desired profile and press Enter
# 4. App will quit and show you the command to switch

Usage

Keyboard Shortcuts

| Key | Action | |-----|--------| | ↑ / k | Move up | | ↓ / j | Move down | | Space | Toggle MCP on/off | | a | Add new MCP | | d | Delete MCP | | r | Restore from backup | | p | Switch profile | | h / ? | Show help | | q / Ctrl+C | Quit |

Profiles

Manage different MCP configurations for different Claude Code instances:

# Method 1: Use --profile flag (recommended)
mcp-manager --profile glm

# Method 2: Set environment variable
CLAUDE_CONFIG_DIR=~/.claude-glm mcp-manager

# Method 3: Switch from within the app
# Press 'p', select profile, press Enter

# Profile naming:
# --profile default → ~/.claude
# --profile glm     → ~/.claude-glm
# --profile work    → ~/.claude-work

Interactive Profile Switching:

1. Press p in the app
2. Navigate to desired profile
3. Press Enter
4. App quits and shows command: mcp-manager --profile <name>
5. Run that command to switch profiles

How It Works

The manager modifies your Claude Code configuration by managing the mcpServers object:

Default profile: ~/.claude.json GLM profile: ~/.claude-glm/.claude.json Custom profile: ~/.claude-<name>/.claude.json

{
  "mcpServers": {
    "fetch-mcp": { "type": "stdio", "command": "node", "args": [...] },
    "brave-search": { "type": "stdio", "command": "npx", "args": [...] }
  },
  "_mcpManagerDisabledServers": {
    "context7-mcp": { "type": "stdio", "command": "npx", "args": [...] }
  }
}

Toggling off moves an MCP to _mcpManagerDisabledServers (saves context tokens). Toggling on moves it back to mcpServers. Deleting removes the server configuration completely.

Development

See docs/development.md for development setup and contribution guidelines.

Documentation

• Architecture - System design and data flow
• User Guide - Detailed usage guide
• Profiles Guide - Profile management and setup
• Development - Contributing and development setup
• Troubleshooting - Common issues and solutions

See CLAUDE.md for critical instructions when working on this project.

Requirements

• Go 1.21 or higher
• Claude Code CLI installed and configured
• macOS, Linux, or Windows

macOS Users: Gatekeeper Issue

If you see [1] killed mcp-manager when running the binary, macOS Gatekeeper is blocking it.

Automatic Fix (Recommended): Use the installation script which handles this automatically:

./scripts/install.sh --build --local

Manual Fix:

xattr -d com.apple.quarantine ~/.local/bin/mcp-manager

Our build and install scripts now automatically remove the quarantine attribute to prevent this issue.

License

MIT License - see LICENSE for details

Credits

Built with:

• Bubble Tea - TUI framework
• Lip Gloss - Terminal styling
• Bubbles - TUI components

Support

• Issues
• Discussions