MCP Switcher – User Guide

Version: 1.0
Date: December 2025
Last Updated: 2025-12-27
Status: Ready for Use

📖 Introduction

Purpose of This Document

This guide explains how to install, configure, and use MCP Switcher—a CLI tool for managing MCP (Model Context Protocol) server configurations and accessing learning resources from SkillsMP. You will learn how to:

Install the application on your system
Create and manage MCP server entries
Enable or disable servers without manual JSON editing
Export clean configurations for use with Cursor, Claude, or other MCP-compatible tools
Search for learning skills using keyword or AI-powered semantic search
Copy skill information to your clipboard for easy reference
Troubleshoot common issues

Scope

This document covers:

Installation on macOS 13.0 and later
Core operations (listing, toggling, creating, removing servers)
Configuration export and integration with Cursor/Claude
Skill search from SkillsMP platform (keyword and AI search)
Clipboard integration for copying skill information
Troubleshooting common problems
Data backup and recovery

This document does not cover:

Internal architecture or design (see ARCHITECTURE.md)
Swift development or building from source (see Sources/ directory)
Contributing to the project (see CONTRIBUTING.md if provided)

Target Audience

End Users: Developers and AI engineers who manage multiple MCP servers
System Administrators: Teams managing shared MCP configurations
Cursor/Claude Users: Anyone integrating MCP Switcher with AI tooling

Prerequisite Knowledge: Basic command-line interface (CLI) experience. No advanced technical knowledge required.

How to Use This Document

Start with "Concept of Operations" if this is your first time using MCP Switcher.
Go to "Installation and Setup" if you need to install the application.
Use "Task-Based Procedures" to find instructions for specific actions (enable a server, export configuration, search skills, etc.).
Check "Troubleshooting" if you encounter problems.
Refer to the "Glossary" for unfamiliar terms.

🎯 Concept of Operations

What Are MCP Servers?

MCP (Model Context Protocol) is a protocol that allows AI models and tools to interact with external data sources and services. An MCP Server is a remote or local endpoint that provides MCP-compatible functionality.

Examples:

A local command that runs code analysis
A remote API endpoint that retrieves data
A service that provides file system access
A tool that connects to a database

The Problem: Manual Configuration

Normally, to use MCP servers with tools like Cursor or Claude, you must:

Edit a JSON configuration file manually
Ensure correct JSON syntax (one mistake breaks everything)
Manage multiple server entries without breaking the structure
Re-generate the file every time you enable or disable a server

This is error-prone and time-consuming.

The MCP Switcher Solution

MCP Switcher eliminates manual JSON editing by providing a simple database and CLI commands:

┌─────────────────────────────────────────┐
│ You: "mcp-switcher enable github"       │
└──────────────┬──────────────────────────┘
               ↓
┌──────────────────────────────────────────┐
│ MCP Switcher Updates SQLite Database     │
└──────────────┬──────────────────────────┘
               ↓
┌──────────────────────────────────────────┐
│ You: "mcp-switcher export"               │
└──────────────┬──────────────────────────┘
               ↓
┌──────────────────────────────────────────┐
│ Clean, Valid JSON Export Generated ✓     │
└──────────────────────────────────────────┘

Typical Workflow

Add servers once (command-based or URL-based)
Enable/disable servers as needed via CLI
Export the configuration when ready to use
Point Cursor/Claude to the exported file
Repeat step 2 whenever you need to change which servers are active

Key Benefits

Benefit	How It Helps
No JSON errors	Automatic validation and generation
Version history	All servers stored in SQLite; easy to revert
Command-line speed	One-command enable/disable instead of file editing
Clean exports	Only enabled servers appear in generated JSON
Backup support	Auto-backups before each export

🚀 Installation and Setup

System Requirements

OS: macOS 13.0 or later
Swift: Swift 5.9 or later
Disk Space: ~50 MB (binary + database)
Network: Internet access for building from source (via Swift Package Manager)

Installation Steps

Step 1: Download and Build

# Clone the repository or navigate to the project directory
cd /Volumes/External/Code/McpSwitcher

# Build the application in release mode
swift build -c release

# The binary will be at: .build/release/mcp-switcher

Step 2: Verify Installation

# Test the binary works
./.build/release/mcp-switcher --version

# Expected output:
# mcp-switcher version 1.0

Step 3: Install to System Path (Optional)

To use mcp-switcher from any terminal, install it to your PATH:

# Create symlink to /usr/local/bin
ln -s $(pwd)/.build/release/mcp-switcher /usr/local/bin/mcp-switcher

# Verify it's accessible
mcp-switcher --version

If you prefer not to create a symlink, you can always run the full path:

/Volumes/External/Code/McpSwitcher/.build/release/mcp-switcher

Step 4: Verify Database Location

MCP Switcher automatically creates a database directory on first run:

# Database location (created automatically):
~/.config/McpSwitcher/mcp-switcher.db

# Backup directory (created automatically):
~/.config/McpSwitcher/backups/

# Verify the directory exists after first run:
ls -la ~/.config/McpSwitcher/

Troubleshooting Installation

Problem: command not found: swift

Solution: Install Xcode Command Line Tools: xcode-select --install

Problem: Build fails with "module not found"

Solution: Ensure you're in the correct directory: cd /Volumes/External/Code/McpSwitcher

Problem: Permission denied when creating symlink

Solution: Use sudo and verify the path: sudo ln -s $(pwd)/.build/release/mcp-switcher /usr/local/bin/mcp-switcher

📚 Task-Based Procedures

This section provides step-by-step instructions for common tasks. Each procedure includes preconditions, numbered steps, and expected results.

Task 1: List All Servers

Purpose: View all MCP servers in your database and their current status.

Preconditions:

MCP Switcher is installed
You have added at least one server (or imported from a JSON file)

Steps:

Open a terminal
Run the list command:
```
mcp-switcher list
```

Expected Result:

NAME                     STATUS          CREATED
─────────────────────────────────────────────────────────────
github                   ✓ ENABLED       2025-12-27T10:30:00Z
context7                 ✗ DISABLED      2025-12-27T10:30:00Z
plane                    ✓ ENABLED       2025-12-27T10:30:00Z

Related Commands:

mcp-switcher list --enabled-only → Show only enabled servers
mcp-switcher list --detailed → Show full configuration for each server

Task 2: Enable a Server

Purpose: Activate a server so it will be included in JSON exports.

Preconditions:

The server exists in your database (check with list)
The server is currently disabled

Steps:

Open a terminal
Run the enable command with the server name:
```
mcp-switcher enable github
```
Or use the server ID (for servers with non-unique names):
```
mcp-switcher enable "550e8400-e29b-41d4-a716-446655440000"
```

Expected Result:

✓ Server 'github' has been enabled.

The server is now active and will appear in JSON exports.

Task 3: Disable a Server

Purpose: Deactivate a server so it will not be included in JSON exports.

Preconditions:

The server exists in your database
The server is currently enabled

Steps:

Open a terminal
Run the disable command:
```
mcp-switcher disable context7
```

Expected Result:

✓ Server 'context7' has been disabled.

The server remains in the database but is excluded from exports.

Task 4: Toggle a Server (Enable ↔ Disable)

Purpose: Quickly switch a server between enabled and disabled states.

Preconditions:

The server exists in your database

Steps:

Open a terminal
Run the toggle command:
```
mcp-switcher toggle plane
```

Expected Result:

If the server was enabled:

✓ Server 'plane' has been disabled.

If the server was disabled:

✓ Server 'plane' has been enabled.

Task 5: View Status Summary

Purpose: Get a quick overview of all servers and their status.

Preconditions:

At least one server exists in your database

Steps:

Open a terminal
Run the status command:
```
mcp-switcher status
```

Expected Result:

MCP Switcher Status
═══════════════════════════════════════
Total Servers:    10
Enabled:          7 ✓
Disabled:         3 ✗

Task 6: Add a New Command-Based Server

Purpose: Create a new server that runs a local command.

Preconditions:

The command you want to run is available on your system
You know the command name and any required arguments

Steps:

Open a terminal

Run the add command with the required parameters:

mcp-switcher add myserver \
  --command "npx" \
  --args "@makeplane/plane-mcp-server" \
  --env "API_KEY=secret,API_HOST=https://example.com" \
  --description "My custom server"

Parameter Explanation:

myserver → Name for your server (must be unique)
--command → The executable to run (e.g., npx, python, node)
--args → Arguments to pass to the command (can be multiple)
--env → Environment variables as comma-separated KEY=VALUE pairs (optional)
--description → Human-readable description (optional)

Expected Result:

✓ Server 'myserver' created successfully.
ID: 550e8400-e29b-41d4-a716-446655440000

Task 7: Add a New URL-Based Server

Purpose: Create a new server that connects to a remote HTTP endpoint.

Preconditions:

You have the URL to an MCP-compatible HTTP endpoint
You know any required headers (e.g., API keys)

Steps:

Open a terminal

Run the add command with the URL parameters:

mcp-switcher add myapi \
  --url "https://api.example.com/mcp" \
  --headers "Authorization=Bearer token123,X-API-Key=secret" \
  --description "Remote MCP endpoint"

Parameter Explanation:

myapi → Name for your server (must be unique)
--url → The HTTP endpoint URL
--headers → HTTP headers as comma-separated KEY=VALUE pairs (optional)
--description → Human-readable description (optional)

Expected Result:

✓ Server 'myapi' created successfully.
ID: 550e8400-e29b-41d4-a716-446655440000

Task 8: Remove a Server

Purpose: Delete a server from your database.

Preconditions:

The server exists in your database
You have confirmed you no longer need this server

Steps:

Open a terminal

Run the remove command:

mcp-switcher remove myserver

The system will ask for confirmation:

Are you sure you want to remove 'myserver'? (yes/no)

Type yes and press Enter

Alternative: Skip confirmation with the --force flag:

mcp-switcher remove myserver --force

Expected Result:

✓ Server 'myserver' has been removed.

The server is deleted permanently and cannot be recovered from the database.

Task 9: Export Configuration to JSON

Purpose: Generate a clean JSON file containing all enabled servers for use with Cursor, Claude, or other tools.

Preconditions:

At least one server is enabled
You know where you want to save the JSON file

Steps:

Open a terminal

Run the export command:

mcp-switcher export --output ~/.cursor/mcp-servers.json

Verify the file was created:
```
ls -la ~/.cursor/mcp-servers.json
```

Expected Result:

The file is created with the following structure:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer github_pat_..."
      }
    },
    "plane": {
      "command": "npx",
      "args": ["-y", "@makeplane/plane-mcp-server"],
      "env": {
        "PLANE_API_KEY": "...",
        "PLANE_API_HOST_URL": "..."
      }
    }
  }
}

Related Options:

--with-metadata → Include additional metadata (timestamps, descriptions)

Task 10: Use Exported Configuration with Cursor

Purpose: Integrate the exported MCP Switcher configuration into Cursor's MCP settings.

Preconditions:

You have exported a configuration file (see Task 9)
Cursor is installed on your system

Steps:

Export your configuration:

mcp-switcher export --output ~/.cursor/mcp-servers.json

Open Cursor settings (or configuration file)

Reference the exported JSON in your MCP configuration:

{
  "mcpServers": {
    // Reference the exported file or copy the contents
  }
}

Restart Cursor or reload settings
Verify the servers are available in Cursor's MCP interface

Note: Refer to Cursor's documentation for exact configuration steps, as they may vary by version.

Task 11: Import Servers from an Existing JSON File

Purpose: Migrate existing MCP server configurations from another tool into MCP Switcher.

Preconditions:

You have an existing MCP server JSON file
The file follows the standard MCP configuration format

Steps:

Open a terminal

Run the import command:

mcp-switcher import ~/my-existing-servers.json

Review the import summary:

✓ Imported 3 servers:
- github
- plane
- context7

Expected Result:

All servers from the JSON file are added to your MCP Switcher database. They are imported as disabled by default; enable them with the enable command (see Task 2).

Task 12: Search Skills from SkillsMP (Keyword Search)

Purpose: Find learning resources and skills using keyword search from the SkillsMP platform.

Preconditions:

You have a SkillsMP API key
Internet connection is available

Steps:

Set your API key as an environment variable (recommended):
```
export SKILLSMP_API_KEY="sk_live_your_api_key_here"
```
Run the keyword search command:
```
mcp-switcher search-skills "SEO"
```

Navigate through pages:

# View specific page
mcp-switcher search-skills "web development" --page 2 --limit 50

# Check pagination info without showing results
mcp-switcher search-skills "web development" --pagination

Advanced search options:

# Search with sorting
mcp-switcher search-skills "machine learning" --sort-by stars
mcp-switcher search-skills "web development" --sort-by recent

# Combined with pagination
mcp-switcher search-skills "react" --sort-by stars --page 2 --limit 50

# Or specify API key directly
mcp-switcher search-skills "AI" --api-key "sk_live_your_key"

Expected Result:

🔍 Skills search results for: 'coder'
   Page 1, 20 of 102 results

📚 Skills:

1. 🎯 pr-review-extraction
   🏷️ Category: undefined
   📊 Difficulty: undefined
   ⭐ Rating: 0.0
   🏷️ Tags: (none)
   🔗 ID: endo-ava-ego-graph-claude-skills-pr-review-extraction-skill-md

2. 🎯 coderabbit-request
   🏷️ Category: undefined
   📊 Difficulty: undefined
   ⭐ Rating: 0.0
   🏷️ Tags: (none)
   🔗 ID: caiokf-dev-profile-claude-skills-coderabbit-request-skill-md

💡 Use --page 2 to see more results
💡 Use 'mcp-switcher copy-skill <id>' to copy a skill to clipboard

Task 13: Search Skills Using AI (Semantic Search)

Purpose: Find learning resources using AI-powered semantic search that understands natural language queries.

Preconditions:

You have a SkillsMP API key
Internet connection is available

Steps:

Set your API key:

export SKILLSMP_API_KEY="sk_live_your_api_key_here"

Run the AI semantic search:

mcp-switcher search-skills-ai "How to create a web scraper"

Or specify API key directly:

mcp-switcher search-skills-ai "build a mobile app" --api-key "sk_live_your_key"

Expected Result:

🤖 AI Skills search results for: 'web scraping'
   Found 10 relevant skills

📚 Skills:

1. 🎯 video-processor
   🏷️ Category: undefined
   📊 Difficulty: undefined
   ⭐ Rating: 5.0
   🔗 ID: basher83-lunar-claude-examples-skills-video-processor-skill-md

2. 🎯 network-framework-ref
   🏷️ Category: undefined
   📊 Difficulty: undefined
   ⭐ Rating: 77.0
   🔗 ID: charleswiltgen-axiom-claude-plugin-plugins-axiom-skills-network-framework-ref-skill-md

💡 Use 'mcp-switcher copy-skill <id>' to copy a skill to clipboard

Task 14: Copy Skill Information to Clipboard

Purpose: Copy detailed skill information to your system clipboard for easy sharing or reference.

Preconditions:

You have found a skill using search commands (Task 12 or 13)
You have the skill ID from the search results

Steps:

Copy a skill by its ID:

mcp-switcher copy-skill "seo_fundamentals_001"

Or specify API key if not set as environment variable:

mcp-switcher copy-skill "python_scraping_101" --api-key "sk_live_your_key"

Expected Result:

✓ Copied skill 'SEO Fundamentals' to clipboard
💡 Skill information is now in your clipboard

Clipboard Content Example:

🎯 pr-review-extraction

📝 Description:
Extract and summarize review comments from GitHub PRs. Use when analyzing PR reviews, checking unresolved issues, or responding to CodeRabbit feedback.

🏷️ Category: undefined
📊 Difficulty: undefined
⏱️ Duration: undefined
⭐ Rating: 0.0
🏷️ Tags:
👤 Author: endo-ava
📅 Updated: 2025-12-27
🔗 URL: https://skillsmp.com/skills/endo-ava-ego-graph-claude-skills-pr-review-extraction-skill-md
🔗 GitHub: https://github.com/endo-ava/ego-graph/tree/main/.claude/skills/pr-review-extraction

Task 15: Use Skills Search GUI (Tray App)

Purpose: Access the SkillsMP skill search through a graphical interface in the system tray.

Preconditions:

Tray app is running (see "Running the Tray App" section)
You have a SkillsMP API key
Internet connection is available

Steps:

Click the MCP Switcher icon in your system menu bar (macOS)
In the popup window, click the "Skills" tab
Enter your SkillsMP API key in the secure field
Enter a search query in the text field
Choose search type:
- Keywords: Paginated results with navigation and sorting controls
- AI Search: Shows all results at once (no pagination or sorting)
For keyword search, select sorting option:
- Default: API default ordering
- Stars: Highest rated skills first
- Recent: Most recently added skills first
Click the search button (magnifying glass for keywords, brain for AI)
Navigate through results:
- Use Previous/Next buttons for pagination (keywords only)
- Click page numbers for direct navigation (if under 10 pages)
- Scroll through the skill list
Copy skills to clipboard:
- Click the copy button (📄 icon) next to any skill
- Skill information is copied to your system clipboard
Open GitHub links:
- Click the link button (🔗 icon) next to skills with GitHub repositories
- Opens the skill's GitHub page in your default web browser
Copy raw GitHub content:
- Click the document button (📄 icon) next to skills with GitHub repositories
- Fetches the raw skill file from GitHub and parses it into a structured format
- Extracts sections, code blocks, and metadata for better readability
- Perfect for importing skills into Claude or other AI assistants

GUI Features:

Pagination Controls: Navigate through large result sets
Sorting Options: Sort by stars, recent, or default (keyword search only)
Search Type Toggle: Switch between keyword and AI search
GitHub Link Opening: Direct links to skill repositories in browser
Raw Content Copying: Fetch and copy raw GitHub skill content to clipboard
Real-time Results: Live updates as you search
Copy to Clipboard: One-click copying of skill information
Error Handling: Clear error messages for API issues

Expected Result:

[Tray App Window]
┌─────────────────────────────────────┐
│ Skills Search        [Servers] [Skills] │
├─────────────────────────────────────┤
│ API Key: [•••••••••••••••••••••••]    │
│ Search: [web development_________] 🔍 🧠 │
│ [Keywords] [AI Search]                 │
│ Sort by: [Default] [Stars] [Recent]    │
├─────────────────────────────────────┤
│ 🎯 React Component Patterns            │
│    ⭐ 4.8 (256 reviews) 🔗 📄 📄     │
│ 🎯 Vue.js Best Practices               │
│    ⭐ 4.6 (189 reviews) 🔗 📄 📄     │
│ [◀ 1 of 5 ▶] [1] [2] [3] [4] [5]      │
│ 250 skills total, showing page 1      │
│                                        │
│ 🔗 = Open GitHub  📄 = Copy Parsed Raw  📄 = Copy Info │
└─────────────────────────────────────┘

What Gets Copied to Clipboard:

Skill Info Copy (📄 Blue Button):

🎯 React Component Patterns
📝 Description: Learn modern React component patterns...
🏷️ Category: Programming
📊 Difficulty: intermediate
⭐ Rating: 4.8 (256 reviews)
🏷️ Tags: react, javascript, frontend
👤 Author: ReactExpert
🔗 SkillsMP URL: https://skillsmp.com/skills/react-patterns
🔗 GitHub URL: https://github.com/ReactExpert/patterns
📅 Updated: Dec 28, 2025

Parsed Raw Copy (📄 Purple Button):

🎯 React Component Patterns
📄 Parsed GitHub Content
══════════════════════════════════════════════════

🏷️ Title: React Component Patterns
🏷️ Description: Modern React patterns guide
🏷️ Author: ReactExpert

📋 Usage
────────────
This skill helps with React component development...

📝 Examples
───────────
```javascript
// Example component
function MyComponent() {
    return <div>Hello React!</div>;
}

══════════════════════════════════════════════════ 🎉 SKILL CONTENT PARSED FROM GITHUB RAW FILE 🎉 📋 ГОТОВ К ИМПОРТУ В CLAUDE DESKTOP ИЛИ ДРУГИЕ AI АССИСТЕНТЫ 📋 🔗 ИСТОЧНИК: GitHub raw content / ПАРСЕНО ИЗ СЫРОГО ФАЙЛА ══════════════════════════════════════════════════


**Note:** AI Search shows all results immediately and doesn't support pagination since it returns semantically relevant results in one batch.

---

## 💾 Data Management

### Where Your Data Is Stored

MCP Switcher stores all server configurations in a SQLite database:

~/.config/McpSwitcher/ ├── mcp-switcher.db (Main database) ├── backups/ (Automatic backups) │ ├── mcp-switcher-2025-12-27-10-30.db.backup │ ├── mcp-switcher-2025-12-27-14-00.db.backup │ └── ...


**Key Details:**
- The `~/.config/` directory is automatically created on your system if it doesn't exist
- The database contains all server names, configurations, and enabled/disabled status
- Backups are created automatically before each export

### Backup and Recovery

**Automatic Backups:**

MCP Switcher creates an automatic backup before each export operation. Backups are stored in `~/.config/McpSwitcher/backups/`.

**Manual Backup:**

To manually back up your database, copy it:

```bash
cp ~/.config/McpSwitcher/mcp-switcher.db ~/my-manual-backup.db

Recovery:

If you need to restore from a backup:

Stop any running MCP Switcher processes

Restore the backup:

cp ~/my-manual-backup.db ~/.config/McpSwitcher/mcp-switcher.db

Verify with mcp-switcher list

🔧 Troubleshooting and Error Resolution

"Server not found" Error

Problem: You run mcp-switcher enable myserver and get an error.

Causes:

The server name is misspelled
The server doesn't exist in your database
You're using a partial name instead of the exact name

Solutions:

Check spelling: List all servers to see exact names
```
mcp-switcher list
```

Use the full server ID if the name is ambiguous:

mcp-switcher enable "550e8400-e29b-41d4-a716-446655440000"

Create the server if it doesn't exist:

mcp-switcher add myserver --command "npx" --args "my-package"

"Database locked" Error

Problem: You get a "database locked" or "database is busy" error.

Causes:

Another instance of MCP Switcher is running
A background process is accessing the database
The database file is corrupted

Solutions:

Check for running processes:
```
ps aux | grep mcp-switcher
```
Kill any running processes:
```
pkill -f mcp-switcher
```
Wait 5–10 seconds and try again
If the problem persists, restore from a recent backup (see "Data Management")

JSON Export Is Empty or Missing Servers

Problem: You run mcp-switcher export but the resulting JSON has no servers or is missing some you expected.

Causes:

No servers are enabled
Servers are disabled and filtered out of the export
The export command syntax is incorrect

Solutions:

Check how many servers are enabled:
```
mcp-switcher list --enabled-only
```

If no servers appear, enable at least one:

mcp-switcher list                    # See all servers
mcp-switcher enable <server-name>    # Enable a server

Run the export again:

mcp-switcher export --output my-config.json

Verify the file exists:
```
cat my-config.json
```

Swift Build Fails

Problem: swift build -c release fails with an error.

Causes:

Swift is not installed or outdated
You're not in the correct directory
Dependency download failed due to network issues

Solutions:

Check Swift version:
```
swift --version
```
If missing, install Xcode Command Line Tools:
```
xcode-select --install
```

Verify you're in the correct directory:

pwd
# Should show: /Volumes/External/Code/McpSwitcher

Clean and rebuild:
```
rm -rf .build
swift build -c release
```
Check internet connection (required for downloading Swift dependencies)

Permission Denied When Installing to /usr/local/bin

Problem: ln -s fails with "Permission denied" when trying to create a symlink in /usr/local/bin.

Solution:

Use sudo to create the symlink with elevated privileges:

sudo ln -s $(pwd)/.build/release/mcp-switcher /usr/local/bin/mcp-switcher

You may be prompted for your password.

No Output from Commands

Problem: Running mcp-switcher list or other commands produces no output.

Causes:

The application has no servers in the database
The database is inaccessible or corrupted
The command syntax is wrong

Solutions:

Check the application version (ensures it's working):
```
mcp-switcher --version
```

If no output, the binary may not be working. Rebuild:

cd /Volumes/External/Code/McpSwitcher
swift build -c release
./.build/release/mcp-switcher list

Verify the database exists:

ls -la ~/.config/McpSwitcher/mcp-switcher.db

If the database is missing, add a server to initialize it:

mcp-switcher add test-server --command "echo" --args "hello"

🗑️ Uninstallation

When to Uninstall

You may want to uninstall MCP Switcher if:

You no longer need to manage MCP servers
You're switching to a different tool or workflow
You want to perform a fresh installation

Uninstallation Steps

Step 1: Remove the Symlink (if installed)

If you created a symlink in /usr/local/bin:

sudo rm /usr/local/bin/mcp-switcher

Step 2: Remove the Binary

If you want to remove the built binary:

cd /Volumes/External/Code/McpSwitcher
rm -rf .build

Step 3: Remove the Database (Optional)

Warning: This permanently deletes all your MCP Switcher server configurations. Only do this if you no longer need them.

rm -rf ~/.config/McpSwitcher/

If you want to keep your data, back it up first:

cp -r ~/.config/McpSwitcher/ ~/mcp-switcher-backup/

Step 4: Verify Removal

which mcp-switcher
# Should output: not found

📖 Glossary

API Key
A secret token used to authenticate requests to a remote service. Do not share API keys publicly.

Backup
A copy of your database file. MCP Switcher creates automatic backups before each export.

CLI (Command-Line Interface)
A text-based interface where you type commands (e.g., mcp-switcher list).

Database
A structured file that stores all your MCP server configurations. MCP Switcher uses SQLite.

Enabled Server
A server that is active and will be included in JSON exports.

Disabled Server
A server that is inactive and will not be included in JSON exports.

Export
The process of generating a clean JSON file from your database containing only enabled servers.

Header (HTTP)
Metadata sent with HTTP requests, often including authentication credentials.

JSON
JavaScript Object Notation—a text format for representing structured data.

MCP (Model Context Protocol)
A protocol that allows AI models and tools to interact with external services and data sources.

MCP Server
An endpoint (local command or remote URL) that provides MCP-compatible functionality.

Symlink
A shortcut to a file or directory. Used to make mcp-switcher accessible from anywhere in the terminal.

SQLite
A lightweight database system used by MCP Switcher to store configurations locally.

UUID
Universally Unique Identifier—a long string (e.g., 550e8400-e29b-41d4-a716-446655440000) that uniquely identifies a server.

🔍 Index

A
- Add a new server: Task 6, Task 7
- Backup and recovery: Data Management section
B
- Backup: Glossary; Data Management section
C
- CLI: Glossary; Installation and Setup section
- Command-based server: Task 6
- Cursor integration: Task 10; Concept of Operations section
D
- Database: Data Management section; Glossary
- Disable a server: Task 3
- Troubleshooting: Troubleshooting section
E
- Enable a server: Task 2
- Export configuration: Task 9; Concept of Operations section
I
- Installation: Installation and Setup section
- Import servers: Task 11
L
- List servers: Task 1
R
- Remove a server: Task 8
S
- Status summary: Task 5
- Symlink: Installation and Setup section; Glossary
T
- Toggle a server: Task 4
- Troubleshooting: Troubleshooting and Error Resolution section
U
- Uninstallation: Uninstallation section
- URL-based server: Task 7

📞 Getting Help

If you encounter issues not covered in this guide:

Check the Troubleshooting section above for common problems
Review the Glossary for unfamiliar terms
Use the Index to find information quickly
Run mcp-switcher --help for command-line help
Contact the developers via the project repository

📄 License

MIT

📝 Document Information

Document Type: User Guide and Installation Guide
Audience: End users, developers, system administrators
Last Reviewed: 2025-12-27
Next Review Date: Recommend quarterly or with each software release

For architecture, design, and contribution information, see separate documentation files (ARCHITECTURE.md, CONTRIBUTING.md).

Made with ❤️ for developers who appreciate clean, simple tools

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
Sources		Sources
Tests/Domain		Tests/Domain
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
DOMAIN_MODEL.md		DOMAIN_MODEL.md
FAVORITES_GUIDE.md		FAVORITES_GUIDE.md
INSTALL.md		INSTALL.md
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
PACKAGE_INFO.txt		PACKAGE_INFO.txt
PERMANENT_PARSING.md		PERMANENT_PARSING.md
PURPLE_BUTTON_SUMMARY.md		PURPLE_BUTTON_SUMMARY.md
Package.swift		Package.swift
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
create_dmg.sh		create_dmg.sh
demo_servers.json		demo_servers.json
manage-tray.sh		manage-tray.sh
simple_test.json		simple_test.json
test_real_api.sh		test_real_api.sh
test_servers.json		test_servers.json
test_skill_search.sh		test_skill_search.sh

Folders and files

Latest commit

History

Repository files navigation

MCP Switcher – User Guide

📖 Introduction

Purpose of This Document

Scope

Target Audience

How to Use This Document

🎯 Concept of Operations

What Are MCP Servers?

The Problem: Manual Configuration

The MCP Switcher Solution

Typical Workflow

Key Benefits

🚀 Installation and Setup

System Requirements

Installation Steps

Step 1: Download and Build

Step 2: Verify Installation

Step 3: Install to System Path (Optional)

Step 4: Verify Database Location

Troubleshooting Installation

📚 Task-Based Procedures

Task 1: List All Servers

Task 2: Enable a Server

Task 3: Disable a Server

Task 4: Toggle a Server (Enable ↔ Disable)

Task 5: View Status Summary

Task 6: Add a New Command-Based Server

Task 7: Add a New URL-Based Server

Task 8: Remove a Server

Task 9: Export Configuration to JSON

Task 10: Use Exported Configuration with Cursor

Task 11: Import Servers from an Existing JSON File

Task 12: Search Skills from SkillsMP (Keyword Search)

Task 13: Search Skills Using AI (Semantic Search)

Task 14: Copy Skill Information to Clipboard

Task 15: Use Skills Search GUI (Tray App)

What Gets Copied to Clipboard:

Skill Info Copy (📄 Blue Button):

Parsed Raw Copy (📄 Purple Button):

🔧 Troubleshooting and Error Resolution

"Server not found" Error

"Database locked" Error

JSON Export Is Empty or Missing Servers

Swift Build Fails

Permission Denied When Installing to /usr/local/bin

No Output from Commands

🗑️ Uninstallation

When to Uninstall

Uninstallation Steps

Step 1: Remove the Symlink (if installed)

Step 2: Remove the Binary

Step 3: Remove the Database (Optional)

Step 4: Verify Removal

📖 Glossary

🔍 Index

📞 Getting Help

📄 License

📝 Document Information

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages