MCP Lightswitch

Ultra-lightweight MCP enable/disable manager for Claude Code. Toggle your Model Context Protocol servers on and off like a lightswitch - no hassle, minimal maintenance.

Why MCP Lightswitch?

Claude Code loads all configured MCPs at startup, consuming significant context tokens even when you're not using them. MCP Lightswitch solves this by providing instant enable/disable functionality with automatic configuration sync.

Key Benefits:

• Low maintenance - sync command discovers new MCPs
• Ultra lightweight - only essential commands, no bloat
• Friendly names - use intuitive names instead of technical MCP names
• Dynamic - works with any MCP without hardcoding

Quick Start

1. Copy Files

Download these files to your Claude Code project directory:

• mcp-manager.sh
• package.json
• mcp-configs.json

2. Setup

# Make script executable
chmod +x mcp-manager.sh

# Initialize with your existing MCPs (if any)
npm run mcp:sync

3. Use

# Dynamic enable/disable
npm run mcp:enable -- notion
npm run mcp:disable -- github

# Enable all configured MCPs
npm run mcp:all

# Check status
npm run mcp:status

# Sync new MCPs
npm run mcp:sync

How It Works

MCP Lightswitch maintains a local mcp-configs.json that acts as persistent memory for your MCP configurations. When you:

1. Install a new MCP with claude mcp add
2. Run sync with npm run mcp:sync
3. It auto-discovers and adds the new MCP to your config

The sync never removes MCPs from your config - it only adds newly discovered ones.

Configuration

Basic Structure

{
  "mcps": {
    "friendly-name": {
      "name": "actual-mcp-name",
      "command": "-- npx some-mcp-server",
      "transport": "stdio",
      "description": "Human readable description"
    }
  }
}

Friendly Names

You can use intuitive names in your config:

{
  "mcps": {
    "browser": {                    // ← Friendly name (customizable)
      "name": "playwright-ext",     // ← Real MCP ID (DO NOT change)
      "command": "-- npx @playwright/mcp@latest",
      "transport": "stdio"
    },
    "files": {                      // ← Friendly name (customizable)
      "name": "filesystem",         // ← Real MCP ID (DO NOT change)
      "command": "-- npx -y @modelcontextprotocol/server-filesystem /allowed/path",
      "transport": "stdio"
    }
  }
}

Then use: npm run mcp:enable -- browser instead of remembering playwright-ext.

Commands

Core Commands

npm run mcp:status       # Show active MCPs
npm run mcp:sync         # Discover & add new MCPs
npm run mcp:enable -- <name>   # Enable specific MCP
npm run mcp:disable -- <name>  # Disable specific MCP
npm run mcp:all          # Enable all from config
npm run mcp:disable-all  # Disable all active MCPs

Examples

Basic Workflow

# Start fresh
npm run mcp:disable-all

# Enable only what you need
npm run mcp:enable -- github
npm run mcp:enable -- browser

# Check what's active
npm run mcp:status

# Add a new MCP to Claude Code
claude mcp add memory -- npx -y @modelcontextprotocol/server-memory

# Sync it to your config
npm run mcp:sync

# Now you can toggle it
npm run mcp:enable -- memory
npm run mcp:disable -- memory

Configuration Example

See mcp-configs.example.json for a complete example with popular MCPs like:

• GitHub (repository access)
• Memory (persistent knowledge)
• Playwright (browser automation)
• Notion (workspace integration)
• Linear (project management)
• Gmail (email integration)

Technical Notes

npm as Script Runner

The package.json uses npm as a universal script runner rather than Node.js project metadata. This is a common pattern because npm is ubiquitous in development environments, provides familiar syntax (npm run command), autocompletion support, and cross-platform compatibility. Essentially using npm as a "command menu" for non-JavaScript projects, leveraging its universal availability rather than creating custom tooling.

Claude Code vs Claude Desktop

This tool is specifically for Claude Code (the CLI/editor), not Claude Desktop. They use different MCP storage systems.

License

MIT