MCP Toggle

MCP切换

为Claude和其他人工智能工具管理、发现和切换MCP服务器

为什么选择MCP切换？

• ⚡ 快速：无需再下载30秒以上的npx-本地服务器将在2-5秒内启动
• 🔄 切换：启用/禁用服务器而不丢失配置
• 🔍 发现：从精选列表中查找并安装50多个流行的MCP服务器
• 🎯 多工具：与克劳德、Cursor、Windsurf、Zed、VSCode合作
• 🚀 自动更新：每周一上午进行一次维护（Oh My Zsh风格）
• 📦 统一：所有AI工具的一个配置

概述

MCP Toggle是一个全面的MCP（模型上下文协议）服务器管理系统，提供：

• 服务器切换：启用/禁用MCP服务器而不丢失其配置
• 服务器发现：从精选的热门MCP服务器列表中浏览和安装
• 多编辑器同步：自动同步Claude、Cursor、Windsurf等设备的MCP配置
• 全局设置：所有工具安装一次，不再需要按工具配置安装
• 自动更新：每周的后台更新使您的服务器保持最新状态

快速开始

1.初始安装

# Clone the repository
git clone https://github.com/dgilperez/mcp-toggle.git
cd mcp-toggle

# Run installation
chmod +x install.sh
./install.sh

这将安装基本的MCP服务器 ~/.mcp/servers/ 并在以下位置创建全局配置 ~/.mcp/global-config.json.使用 discover 添加更多服务器。

2.设置API密钥（可选）

为您计划使用的服务器设置API密钥。添加到您的 ~/.zshrc 或 ~/.bashrc:

# Only add keys for servers you'll use
export BRAVE_API_KEY='your-key'      # For brave-search
export GH_TOKEN='your-token'          # For github
export NOTION_API_KEY='your-key'      # For notion
# ... add others as needed

然后重新加载：

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

3.更新您的工具

# Update Claude config

# Sync to all tools (Claude, Cursor, Windsurf, Zed, VSCode)
./bin/sync-all.sh

核心功能

1.打开/关闭服务器

在不丢失配置的情况下启用和禁用MCP服务器：

# List all servers and their status (or just run without args)
./mcp-toggle
./mcp-toggle info

# Disable a server (moves to _disabled_mcpServers)
./mcp-toggle disable figma

# Enable a server (moves back to mcpServers)
./mcp-toggle enable figma

# Bulk operations - enable/disable multiple servers at once
./mcp-toggle enable figma puppeteer notion
./mcp-toggle disable github brave-search

禁用的服务器保留在 _disabled_mcpServers 部分-它们不会被加载，但配置会被保留。

2.服务器信息和运行状况

检查所有服务器的运行状况或获取特定服务器的详细信息：

# Health check ALL enabled servers
./mcp-toggle info

# Shows for each server:
# - Status with impact indicator (🔴 Heavy, 🟡 Medium, 🟢 Light)
# - Command availability check
# - Environment variables check
# - Summary with issue count and recommendations

# Detailed info for specific server
./mcp-toggle info filesystem

# Shows:
# - Status: ENABLED/DISABLED
# - Context Window Impact: Heavy/Medium/Light
# - Configuration details
# - Health Check: command availability, environment variables
# - Impact guidance

影响程度：

• 重的：1000+令牌（文件系统、figma、木偶师、黑曜石）
• 中等：100-1000个代币（github、数据库、概念）
• 光：\<100个令牌（搜索、松弛、官方服务器）

3.发现服务器

浏览精心策划的服务器或搜索npm-所有这些都在一个命令中：

# Show curated list of popular servers
./mcp-toggle discover

# Browse by category
./mcp-toggle discover database      # Database-related servers
./mcp-toggle discover productivity  # Productivity tools
./mcp-toggle discover dev-tools     # Development tools

# Search npm for anything else
./mcp-toggle discover weather       # Searches npm if not a known category

发现功能包括15个以上精心策划的类别，其中包含影响指标：

• 数据库：PostgreSQL、SQLite
• 生产力：Notion、黑曜石、Slack
• 发展：GitHub，Puppeteer
• 搜索：勇敢，PubMed
• AI&官方：记忆，顺序思维
• 从缓存中动态提取更多类别

4.使用分析

深入了解您的服务器配置并获得建议：

# Show statistics and recommendations
./mcp-toggle stats

显示器：

• 启用/禁用服务器计数
• 按类别（重型/中型/轻型）划分的影响明细
• 估计上下文使用基线
• 基于您的设置的智能推荐

5.多编辑器支持

跨多个编辑器同步MCP配置：

# Sync to all supported editors
./bin/sync-all.sh

# This updates:
# - Claude Code (~/.claude.json)
# - Cursor (~/.config/cursor/mcp.json)
# - Windsurf (~/.codeium/windsurf/mcp.json)
# - Zed (~/.config/zed/settings.json)
# - VSCode (multiple locations)

每个编辑器都会收到一个格式正确的配置，其中包含：

• 环境变量替换
• 编辑器特定的路径和格式
• 自动服务器发现

6.自动更新

MCP服务器会在每周一启动新终端时自动更新（Oh My Zsh风格）：

• 频率：每周一上午
• 背景：运行时不会阻止终端启动
• 日志记录：结果记录到 ~/.cache/mcp/update.log
• 聪明的：仅在7+天后更新
• 强制更新：如果错过星期一，则14天后

它是如何工作的：

1. 检查自上次更新以来是否已超过7天
2. 如果是星期一（或超过14天），在后台运行更新
3. 将结果记录到 ~/.cache/mcp/update.log
4. 不会阻止终端启动

检查更新状态：

# When last updated
cat ~/.cache/mcp/.mcp-update

# View update log
tail ~/.cache/mcp/update.log

# Force update now
mcp-update

禁用自动更新：

# Add to ~/.zshrc
export DISABLE_MCP_AUTO_UPDATE="true"

自动更新故障排除：

• 如果更新未运行，请检查 echo $DISABLE_MCP_AUTO_UPDATE 未设置为“true”
• 检查日志文件： tail ~/.cache/mcp/update.log
• 手动更新： mcp-update

日常使用

使用Claude代码

正常启动Claude Code：

claude

它将自动使用快速的全局MCP服务器。别再等了！

在Python脚本中使用

import subprocess
from pathlib import Path

mcp_config = Path.home() / '.mcp' / 'global-config.json'

with open(mcp_config) as f:
    config = f.read()

result = subprocess.run([
    'claude',
    '--strict-mcp-config',
    '--mcp-config', config,
    '--print', 'Your prompt here'
], capture_output=True, text=True)

测试MCP工具

测试已安装的服务器是否正常工作：

# Test filesystem access
claude --print "List files in my home directory using filesystem"

# Test web fetching
claude --print "Fetch the content from example.com using fetch"

通过安装更多服务器后 discover，同样地测试它们。

维护

手动更新

手动更新所有MCP服务器：

mcp-update

或仅更新软件包：

cd ~/.mcp/servers
npm update

检查更新状态：

# Check last update
cat ~/.cache/mcp/.mcp-update

# Check update log
tail ~/.cache/mcp/update.log

添加新的MCP服务器

1. 安装它：

cd ~/.mcp/servers
npm install @org/new-mcp-server

1. 添加到 ~/.mcp/global-config.json:

"new-server": {
  "command": "node",
  "args": ["$HOME/.mcp/servers/node_modules/@org/new-mcp-server/dist/index.js"],
  "env": {
    "API_KEY": "${NEW_API_KEY}"
  }
}

1. 同步到所有工具：

./bin/sync-all.sh

检查已安装的版本

cd ~/.mcp/servers
npm list --depth=0

文件位置

可用的MCP服务器

安装后，您将拥有：

• 文件系统：本地文件操作
• 获取：Web内容获取

发现并安装更多：

./mcp-toggle discover      # Browse 50+ curated servers
cd ~/.mcp/servers && npm install @modelcontextprotocol/server-github
# Then add to config and sync

性能比较

故障排除

MCP工具不可用

1. 检查是否已安装：

ls ~/.mcp/servers/node_modules/ | grep your-server

1. 检查它是否在配置中：

cat ~/.mcp/global-config.json | jq '.mcpServers | keys'

1. 检查服务器信息：

./mcp-toggle info your-server

1. 如果需要，请重新启动编辑器

API关键错误

1. 验证密钥已设置：

echo $YOUR_API_KEY

1. 检查它是否已导出到~/.zshrc中
2. source ~/.zshrc 重新加载

性能缓慢

这不应该发生在本地设置中！如果是这样：

1. 检查你没有使用旧的Smithery配置
2. 通过以下方式进行验证： jq '.mcpServers.brave.command' ~/.claude.json
3. 应显示“node”，而不是“npx”

服务器切换不起作用

1. 检查配置是否为有效的JSON：

jq . ~/.mcp/global-config.json

1. 每次切换之前，都会在以下位置创建备份：

ls -la ~/.mcp/*.backup

1. 如果需要，从备份还原：

cp ~/.mcp/global-config.json.backup ~/.mcp/global-config.json

有关更多故障排除帮助，请参阅 docs/TROUBLESHOOTING.md.

高级用法

使用不同的配置

您可以为不同目的维护多个配置：

# Production config
~/.mcp/global-config.json

# Development config
~/.mcp/dev-config.json

# Minimal config for testing
~/.mcp/minimal-config.json

在它们之间切换：

claude --mcp-config ~/.mcp/dev-config.json

环境特定密钥

根据环境使用不同的密钥：

# Development
export BRAVE_API_KEY=$BRAVE_API_KEY_DEV

# Production
export BRAVE_API_KEY=$BRAVE_API_KEY_PROD

贡献

我们欢迎捐款！请看 贡献.md 一般指导方针。

贡献服务器元数据

MCP服务器缓存(data/mcp-cache.json)每周自动更新。贡献：

1. 用启发式方法估计影响:

   # Run locally to estimate token impact
   ./scripts/measure-impact.sh

使用基于研究的估计（~400-500个令牌/工具）和常见服务器的已知模式。

1. 从您的实际使用情况中提取 （最准确）：

   # Analyze your Claude Code JSONL logs
   ./scripts/extract-mcp-baseline.sh

解析真实会话数据以提取基线令牌消耗。显示哪些MCP服务器 他们很活跃，并估计了他们的开销。

1. 添加手动测量 （建议PR使用）：

- 使用克劳德代码 /context 获取每台服务器令牌计数的命令 - 添加到 data/manual-metadata.json 随着 "method": "measured"

1. 提交PR -请参阅 docs/CONTRIBUTING_CACHE.md 详见

影响评估的工作原理：

• 研究表明，MCP工具定义通常每个使用约400-500个令牌
• 启发式脚本应用已知模式：重型（1200+）、中型（500）、轻型（150）
• JSONL提取提供了真实的会话数据，但无法隔离单个服务器
• 要获得精确的每台服务器数据，请使用 /context 克劳德代码
• 影响类别：重度（1000+代币）、中度（100-1000）、轻度（\<100）

缓存系统：

• 从MCP官方注册表+npm统计中提取
• 与手动元数据合并（欢迎PR！）
• 每周日晚上自动重新生成
• 支持中的本地覆盖 ~/.mcp/local-metadata.json

安全说明

• 永远不要将API密钥提交到git
• 为所有键使用环境变量
• 所有敏感文件都在 .gitignore
• 考虑在生产中使用机密管理器
• 定期旋转API密钥
• 存储库已经过安全审计（git历史中没有秘密）

文档

• 故障排除指南 -常见问题和解决方案
• 贡献指南 -如何做出贡献
• 缓存贡献 -添加服务器元数据和影响评级
• 更新日志 -版本历史和更改

资源

• MCP文件：https://modelcontextprotocol.io/
• 克劳德代码文档：https://docs.anthropic.com/claude/docs
• 问题：

许可证

MIT许可证-请参阅 许可证 详细信息文件

______________________________________________________________________

最后更新: 2025-01-19 版本: 1.0.0