cmcp - CLI MCP Manager

A command-line tool for managing Model Context Protocol (MCP) servers on your system.

Features

• Claude CLI Integration - Registers/unregisters servers with Claude CLI for seamless use
• Persistent Configuration - Store MCP server configurations independently from Claude
• Interactive server selection - Select servers to start/stop using arrow keys
• Manual config editing - Open config file directly in nano with cmcp config open
• Shell autocompletion - Full command completion support for bash, zsh, fish, and PowerShell
• Standard MCP format - Compatible with Claude Desktop and other MCP tools
• Advanced Troubleshooting - Built-in diagnostics help identify and fix MCP connection issues
• Debug Logging - Automatic debug output capture for troubleshooting failures
• Orphaned Server Cleanup - Detect and clear servers from Claude that aren't in your config

Requirements

• Claude CLI - Required for server registration (uses claude mcp add/remove/list)
• Go 1.21+ - For building the tool
• nano (preferred) or any text editor

Supported Operating Systems

• macOS (Intel and Apple Silicon)

  • Full support including Homebrew integration
  • Tested on macOS 12+ (Monterey and later)

• Linux (x86_64 and ARM64)

  • Ubuntu, Debian, Fedora, Arch, and other major distributions
  • Requires standard Unix tools (bash, grep, etc.)

• Windows - Not currently supported

  • The tool relies on Unix shell scripts and Claude CLI
  • Windows users can use WSL2 (Windows Subsystem for Linux)

Installation

Quick Install (Recommended)

Install cmcp with a single command:

# Install
curl -sSL https://raw.githubusercontent.com/lopezm94/cmcp/main/scripts/web-install.sh | bash

# Uninstall
curl -sSL https://raw.githubusercontent.com/lopezm94/cmcp/main/scripts/web-uninstall.sh | bash

Manual Installation

# Clone and install cmcp
git clone https://github.com/lopezm94/cmcp.git
cd cmcp

# Install or upgrade (automatically detects existing installation)
./scripts/install.sh

# To uninstall completely
./scripts/uninstall.sh

Installation Scripts

• ./scripts/install.sh - Install or upgrade cmcp

  • Automatically detects if this is a fresh install or upgrade
  • Builds and installs the binary to /usr/local/bin
  • Sets up shell completions for your shell
  • Always preserves existing server configurations
  • For upgrades: shows version info and offers to stop running servers
  • For fresh installs: creates the configuration directory ~/.cmcp

• ./scripts/uninstall.sh - Remove cmcp from your system

  • Removes the cmcp binary
  • Removes shell completions
  • Optionally removes configuration (asks for confirmation)
  • If you keep the configuration, you can reinstall later and retain all server settings

Usage

This tool stores MCP server configurations and registers them with Claude CLI when starting.

How it works

1. cmcp stores server configurations in its own config file
2. cmcp start uses claude mcp add to register servers with Claude for the current project
3. cmcp stop uses claude mcp remove to unregister servers from Claude for the current project
4. cmcp online uses claude mcp list to show Claude's registered servers with status indicators

Configure and Start MCP Servers

# Open config file to add servers manually
cmcp config open
# Add servers in the standard MCP format - example:
# {
#   "mcpServers": {
#     "github": {
#       "command": "npx",
#       "args": ["-y", "@modelcontextprotocol/server-github"],
#       "env": {
#         "GITHUB_TOKEN": "ghp_your_token_here"
#       }
#     }
#   }
# }

# Start the server (registers with Claude)
cmcp start
# Select: github

# Verify it's running (shows Claude's registered servers)
cmcp online

Manage Configuration

# Edit configuration file directly
cmcp config open
# Opens ~/.cmcp/config.json in nano

# List configured servers
cmcp config list

# Remove a server (interactive selection)
cmcp config rm

Example Configuration

Edit your config file to add servers like these:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["@claude/mcp-server-filesystem"],
      "env": {
        "ALLOWED_DIRECTORIES": "/home/user/documents,/home/user/projects"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    },
    "sqlite": {
      "command": "npx",
      "args": ["@claude/mcp-server-sqlite", "--db", "/path/to/database.db"]
    }
  }
}

Manage Servers

# Start a server (interactive selection, registers with Claude for this project)
cmcp start

# Start with verbose output to see debug output directly
cmcp start -v

# Stop a running server (interactive selection, unregisters from Claude)
cmcp stop

# Show all servers registered in Claude for this project with colored status indicators
cmcp online

# Clear orphaned servers (not in your config) from Claude
cmcp online --clear

# Remove failed servers from Claude
cmcp online --clean

# Stop all running servers (unregisters all from Claude for this project)
cmcp reset

Troubleshooting MCP Connections

cmcp includes advanced diagnostics and automatic debug logging:

Automatic Debug Logging

Debug output is always captured when commands fail:

• In normal mode: Debug logs are saved to /tmp/cmcp-debug/ and the path is shown in error messages
• In verbose mode (-v): Debug output from Claude CLI is shown directly in the terminal

# Normal mode - debug log saved to file on error
cmcp start github
# If it fails: ✗ Failed to start server 'github' (debug log: /tmp/cmcp-debug/cmcp-start-github-20250807-150625.log)

# Verbose mode - see debug output directly
cmcp start -v github

The diagnostics provide intelligent analysis for common issues:

• Docker servers: Checks if Docker daemon is running, image availability, environment variables
• Node.js servers: Verifies node/npx installation, script existence, dependencies
• Python servers: Checks Python installation, script availability, requirements
• General issues: Permission errors, port conflicts, missing environment variables

Example output when troubleshooting:

Starting server 'github'...
✗ Failed to start server 'github':
server 'github' failed to start: failed to connect

Health Check: github: docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server - ✗ Failed to connect

Error Output:
docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.

Possible solutions:
  1. Docker daemon is not running. Please start Docker Desktop or the Docker service.
  2. Check that required environment variables are set in your shell

Managing Orphaned and Failed Servers

Orphaned servers (added directly with claude mcp add or from tests, not in your cmcp config):

# View all servers with status indicators
cmcp online
# Output:
# MCP servers running in Claude for this project:
# Project: /path/to/your/project
# 
# ✓ github: npx -y @modelcontextprotocol/server-github - Connected
# ✗ test-fail: nonexistent-command --fail - Failed to connect
# 
# ⚠ Found 1 server(s) in Claude that are not in your cmcp config:
#   - test-fail
# 
# To clear these servers from Claude, run:
#   $ cmcp online --clear

# Clear orphaned servers
cmcp online --clear
# or with dry-run to preview
cmcp online --clear --dry-run

Failed servers (servers in your config that are failing to connect):

# Remove all failed servers from Claude
cmcp online --clean

# Preview what would be removed
cmcp online --clean --dry-run

Security Note: All sensitive information (API keys, tokens, passwords) are automatically masked in verbose and debug output to prevent accidental exposure.

Shell Completion

Shell completion is automatically installed by ./install.sh and adds automcompletion to zsh.

For manual setup:

# Zsh
cmcp completion zsh > "${fpath[1]}/_cmcp"

Configuration

Configuration is stored in ~/.cmcp/config.json using the standard MCP format:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Benefits of the standard format:

• ✅ Compatible with Claude Desktop configuration
• ✅ Can copy servers between cmcp and Claude
• ✅ Edit config file manually for advanced setups
• ✅ Industry standard MCP configuration

Testing

Run comprehensive tests in an isolated container:

# Run all tests (automatically detects Podman or Docker)
./test.sh

# Run specific tests
./test.sh online              # Test online command features
./test.sh logging             # Test automatic logging functionality
./test.sh unit comprehensive  # Run multiple specific tests

# Available test names:
# - unit: Go unit tests
# - comprehensive: Comprehensive functionality tests
# - install: Install/uninstall script tests
# - logging: Automatic logging tests
# - web: Web install/uninstall tests
# - online: Online command tests

The test suite covers:

• All command functionality
• Interactive prompts
• Server lifecycle management
• Configuration persistence
• Error handling
• Debug logging
• Orphaned server cleanup

Tests run in a clean environment and don't affect your system.

License

MIT