mcp-context-switcher

Context-aware MCP server profile management for Claude Code. Load only the servers you need.

---

The Problem

Every MCP server you load costs tokens. With 5+ servers you burn 15-40K tokens of context window on tool definitions you don't need for the current task. That's context you could spend on actual work.

Switching manually is tedious: edit JSON, restart, remember which servers you needed. Most people just load everything and waste context on every session.

BEFORE (everything loaded always):
  Writing docs?  10 servers loaded  =  40K tokens wasted
  Quick chat?    10 servers loaded  =  40K tokens wasted
  Coding?        10 servers loaded  =  only 5 needed

AFTER (mcp-context-switcher):
  Writing docs?  0 servers  =  0K tokens  (auto-detected)
  Quick chat?    0 servers  =  0K tokens  (auto-detected)
  Coding?        3 servers  = 15K tokens  (auto-detected)

The Solution

mcp-context-switcher auto-detects your project type from the working directory and loads only the right MCP servers. Zero overhead when you don't need them, full power when you do.

• Auto-detection: JSON rules match directory patterns to profiles
• Token tracking: Each profile declares its token cost
• Safe switching: Automatic backup before every switch, one-command rollback
• Interactive prompt: Y/n/l check shows what will change before switching
• Claude Code skill: /mcp-start runs the check from inside a session

---

Comparison with Alternatives

Feature	mcp-context-switcher	mcpm.sh	claude-mcp-manager	claude-manager
Auto-detection from PWD	Yes	No	No	No
Token cost tracking	Yes	No	No	No
Configurable JSON rules	Yes	No	No	No
Claude Code CLI native	Yes	Partial	CLI only	GUI only
Rollback with backup	Yes	No	No	No
Claude Code /skill	Yes	No	No	No
Shell completions	bash + zsh	No	No	No
Env var resolution	Yes	No	Yes	No
Profile validation	Yes	No	No	No
Zero dependencies	bash + jq	Node.js	Python	Electron

---

Quick Start

Install

# Clone and install
git clone https://github.com/Luigigreco/mcp-context-switcher.git
cd mcp-context-switcher
bash install.sh

# Reload shell
source ~/.zshrc  # or ~/.bashrc

First Use

# Check which profile is right for your current directory
mcp

# Or start Claude Code with automatic profile check
ccs

One-Liner Install (after first release)

curl -fsSL https://raw.githubusercontent.com/Luigigreco/mcp-context-switcher/main/install.sh | bash

---

How It Works

  1. You cd into a project directory
  2. mcp-context-switcher reads detection-rules.json
  3. Rules are sorted by priority, regex patterns matched against PWD
  4. First matching rule determines the profile
  5. If current profile differs from detected: prompt Y/n/l
  6. On switch: backup current config, apply new profile, update state
  7. Restart Claude Code to load new servers

Detection Rules

Rules are defined in ~/.claude/config/mcp-profiles/detection-rules.json:

{
  "rules": [
    {
      "name": "web-dev",
      "priority": 10,
      "profile": "dev",
      "patterns": [".*/src/.*", ".*/app/.*", ".*/frontend/.*"],
      "description": "Web development projects"
    }
  ],
  "default_profile": "default"
}

Higher priority wins. If no rule matches, default_profile is used.

---

Commands

Command	Description
mcp-context-switcher detect	Auto-detect optimal profile for PWD and switch
mcp-context-switcher switch <name>	Switch to a specific profile
mcp-context-switcher current	Show active profile with server list
mcp-context-switcher list	List all available profiles
mcp-context-switcher rollback	Restore previous configuration
mcp-context-switcher report	Show switch history and statistics
mcp-context-switcher init	Initialize config directory with defaults
mcp-context-switcher validate	Validate all profile JSON files

Shell Aliases

After install, these aliases are available:

Alias	Expands to
mcp	Interactive profile check (Y/n/l)
mcps	Show current profile
mcpl	List all profiles
ccs	Smart-start Claude Code with profile check

---

Creating Your Own Profiles

Profiles are JSON files in ~/.claude/config/mcp-profiles/. Each file needs:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@scope/mcp-server-package"],
      "env": {
        "API_KEY": "$MY_API_KEY"
      }
    }
  },
  "metadata": {
    "profile_name": "my-profile",
    "description": "What this profile is for",
    "token_cost": "~20K",
    "use_case": "When to use this profile"
  }
}

Environment Variables

Use $VAR_NAME or ${VAR_NAME} in profile values. They're resolved at switch time from your shell environment.

Example: Data Science Profile

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "$HOME/data"]
    }
  },
  "metadata": {
    "profile_name": "data-science",
    "description": "GitHub + filesystem access for data projects",
    "token_cost": "~12K"
  }
}

Then add a detection rule:

{
  "name": "data-science",
  "priority": 8,
  "profile": "data-science",
  "patterns": [".*/notebooks?/.*", ".*/data-.*", ".*/ml/.*"]
}

---

Auto-Detection Rules

See docs/AUTO-DETECTION.md for the full guide on writing custom detection rules.

Key points:

• Rules use regex patterns matched against the full $PWD path
• Higher priority values take precedence
• Multiple patterns per rule (any match triggers the rule)
• default_profile is the fallback when no rule matches

---

Claude Code Skill

After install, the /mcp-start skill is available inside Claude Code sessions. It runs the same detection logic and shows the profile recommendation inline.

The skill file is installed to ~/.claude/skills/mcp-start/SKILL.md.

---

Configuration

See docs/CONFIGURATION.md for all configuration options.

Config File

Optional config at ~/.claude/config/mcp-context-switcher.conf:

MCS_CONFIG_DIR="$HOME/.claude/config/mcp-profiles"
MCS_DETECTION_RULES="$MCS_CONFIG_DIR/detection-rules.json"
MCS_STATE_FILE="$MCS_CONFIG_DIR/.mcp-profile-state"
MCS_BACKUP_DIR="$MCS_CONFIG_DIR/backups"
MCS_LOG_FILE="$HOME/.claude/logs/mcp-context-switches.log"
MCS_MAX_BACKUPS=10
MCS_TARGET_FILE="$HOME/.claude/settings.json"

---

Requirements

• bash 4.0+ (macOS ships with 3.2 but it works; for full features use brew install bash)
• jq for JSON processing (brew install jq / apt install jq)
• Claude Code CLI (the tool you're managing profiles for)

---

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feature/my-feature)
3. Run tests: bash tests/test-detect.sh
4. Run ShellCheck: shellcheck bin/*.sh
5. Submit a PR

---

License

MIT

---

Built by Luigi Greco. Born from the pain of managing multiple MCP profiles across different project types.