MCP Commander

A convenient command-line tool to manage MCP (Model Context Protocol) servers across different code editors.

🚀 Features

Core MCP Operations

• Multi-Editor Support: Manage MCP servers for Claude Code, Claude Desktop, Cursor, and VS Code
• Flexible Server Management: Add, remove, and list servers across all or specific editors
• Status Monitoring: Check configuration file status and server counts
• Rich CLI Interface: Colorized output with tables and status indicators

Advanced Management

• 🔍 Auto-Discovery: Automatically discover all MCP configurations on your system
• 🌍 Add-All Command: Install servers to ALL discovered MCP configurations at once
• 📊 Status Dashboard: Comprehensive status overview of all editor configurations
• ⚙️ Configuration Validation: Pydantic-based configuration validation and error handling

Developer Experience

• Type Safety: Full type hints and mypy compatibility
• Error Handling: Detailed error messages with actionable guidance
• Extensible: Easy to add support for new editors and MCP clients
• Testing: Comprehensive test coverage with pytest

📦 Installation

Option 1: From PyPI (Recommended)

# Install globally
pip install mcp-commander

# Or using pipx for isolated installation
pipx install mcp-commander

Option 2: From Git Repository

# Install directly from GitHub
pip install git+https://github.com/nmindz/mcp-commander.git

# Or clone and install
git clone https://github.com/nmindz/mcp-commander.git
cd mcp-commander
pip install .

Option 3: Development Installation

git clone https://github.com/nmindz/mcp-commander.git
cd mcp-commander
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Option 4: Direct Execution (No Installation Required)

# Clone repository
git clone https://github.com/nmindz/mcp-commander.git
cd mcp-commander

# Install dependencies only
pip install -r requirements-dev.txt

# Method A: Using run.py script
python run.py --help
python run.py list

# Method B: Using shell wrapper
./mcp.sh --help
./mcp.sh discover

# Method C: Using Python module syntax (cleanest)
PYTHONPATH="src:$PYTHONPATH" python -m mcpcommander --help
PYTHONPATH="src:$PYTHONPATH" python -m mcpcommander status

Requirements

• Python 3.12 or higher
• Works on macOS, Windows, and Linux

💡 Getting Help

Contextual Examples

Use --help --verbose (or --help -v) to see practical examples for any command:

# Show detailed help with examples
mcp add --help --verbose
mcp add-editor --help --verbose
mcp status --help --verbose

# Regular help (without examples)
mcp add --help

Configuration Examples

View all transport configuration examples:

# Show all transport examples
mcp examples

# Show examples with usage instructions
mcp examples --verbose

💻 Commands

🔍 Discovery and Status

# Discover all MCP configurations on your system
mcp discover

# Check status of all editor configurations
mcp status

# List available editors
mcp editors

📝 Server Management

# List all configured servers
mcp list

# List servers for a specific editor
mcp list claude-code

# Add server to specific editor
mcp add myserver "npx @modelcontextprotocol/server-filesystem /tmp" claude-code

# Add server to all configured editors
mcp add myserver "npx @modelcontextprotocol/server-filesystem /tmp"

🌍 Environment Variable Support

# Copy environment variables from current environment
export MCP_LOG_LEVEL=info
export GIT_SIGN_COMMITS=false
mcp add git-server "npx @cyanheads/git-mcp-server" --from-env=MCP_LOG_LEVEL,GIT_SIGN_COMMITS

# Set explicit environment variables
mcp add api-server "npx my-api-server" --env=DEBUG:true --env=API_KEY:secret123

# Combine both approaches
mcp add hybrid-server "npx server" --from-env=LOG_LEVEL --env=CUSTOM_VAR:custom_value

# Use with JSON configuration (merges environment variables)
mcp add json-server '{"command": "npx", "args": ["server"], "env": {"EXISTING": "value"}}' --env=NEW_VAR:added

# Global verbose mode via environment variable
export MCP_COMMANDER_VERBOSE=1
mcp list  # Will run in verbose mode automatically

Generated Configuration

When using environment variables, MCP Commander generates server configurations like this:

{
  "mcpServers": {
    "git-mcp-server": {
      "command": "npx",
      "args": ["@cyanheads/git-mcp-server"],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "GIT_SIGN_COMMITS": "false"
      }
    }
  }
}

🌍 NEW: Add to All Discovered Configurations

# Automatically discover and install to ALL MCP configurations
mcp add-all myserver "npx @modelcontextprotocol/server-filesystem /tmp"

# Works with JSON configurations too
mcp add-all myserver '{"command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"]}'

🗑️ Server Removal

# Remove server from all configured editors
mcp remove myserver

# Remove server from specific editor
mcp remove myserver cursor

ℹ️ Help and Version

# Show help
mcp --help
mcp help  # Same as above

# Show version
mcp version

Configuration

MCP Commander automatically manages its configuration in platform-specific user directories:

• Windows: %APPDATA%/mcpCommander/config.json
• macOS: ~/Library/Application Support/mcpCommander/config.json
• Linux: ~/.config/mcpCommander/config.json

When you first run any command, mcpCommander will automatically:

1. Create the user config directory
2. Migrate any existing config.json from the repository
3. Create a default config if none exists

The configuration defines which editors are supported and where their configuration files are located:

{
  "editors": {
    "claude-code": {
      "config_path": "~/.claude.json",
      "jsonpath": "mcpServers"
    },
    "claude-desktop": {
      "config_path": "~/Library/Application Support/Claude/claude_desktop_config.json",
      "jsonpath": "mcpServers"
    },
    "cursor": {
      "config_path": "~/.cursor/mcp.json",
      "jsonpath": "mcpServers"
    }
  }
}

Adding New Editors

To add support for a new editor, simply add an entry to the editors object in config.json:

{
  "editors": {
    "new-editor": {
      "config_path": "/path/to/editor/config.json",
      "jsonpath": "mcpServers"
    }
  }
}

The jsonpath field supports simple dot notation for nested JSON paths (e.g., "config.mcpServers").

File Structure

mcpCommander/
├── config.json          # Editor configuration
├── mcp_manager.py       # Main Python script
├── mcp                  # Shell wrapper script
└── README.md           # This file

Examples

Managing your JIRA MCP server

# Add JIRA server to all editors
mcp add jira-mcp "~/Projects/me/jira-mcp/server.py"

# List all configured servers
mcp list

# Remove from just Cursor
mcp remove jira-mcp cursor

# Check what's configured
mcp status

Adding a server with complex configuration

mcp add filesystem '{"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Documents"]}'

🛠️ Development

Local Development Setup

# Clone the repository
git clone https://github.com/nmindz/mcp-commander.git
cd mcp-commander

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run linting and formatting
black src/ tests/
flake8 src/ tests/
mypy src/

Project Structure

mcp-commander/
├── src/mcpcommander/          # Main package
│   ├── core/                  # Core business logic
│   ├── cli/                   # Command-line interface
│   ├── utils/                 # Utilities and helpers
│   └── schemas/               # Pydantic schemas
├── tests/                     # Test suite
│   ├── unit/                  # Unit tests
│   ├── integration/           # Integration tests
│   └── e2e/                   # End-to-end tests
├── docs/                      # Documentation
└── scripts/                   # Automation scripts

Requirements

• Python 3.12 or higher
• Cross-platform (macOS, Windows, Linux)
• Rich CLI output with colorized formatting

🆕 What's New in v2.0

🔍 Auto-Discovery System

• Automatically finds all MCP configurations on your system
• Supports Claude Code, Claude Desktop, Cursor, VS Code, and more
• Cross-platform detection (macOS, Windows, Linux)

🌍 Add-All Command

# One command to rule them all!
mcp add-all my-server "npx @modelcontextprotocol/server-filesystem /tmp"

• Discovers ALL MCP configurations automatically
• Installs server to every found configuration
• Detailed success/failure reporting with colors

📊 Enhanced CLI Experience

• Rich table formatting for server listings
• Colorized status indicators (✅❌⚠️)
• Comprehensive error messages with actionable guidance
• Verbose logging options for debugging

🏗️ Modern Architecture

• Enterprise-grade error handling with custom exceptions
• Type safety with comprehensive type hints
• Extensive test coverage (85%+)
• Modern Python packaging with pyproject.toml

🔧 Troubleshooting

Common Issues

• Configuration not found: Run mcp discover to see all available MCP configurations
• Permission errors: Ensure you have write access to editor configuration directories
• JSON validation errors: Use mcp status to check configuration file integrity
• Server conflicts: Use mcp list to see existing servers before adding new ones

Debug Mode

# Enable verbose output for debugging
mcp add-all myserver "command" --verbose
mcp list --verbose

Getting Help

# Comprehensive help for any command
mcp --help
mcp add-all --help