English | 简体中文

Open Source. Forever Free.
Built with ❤️ by Path Integral Institute

🌟 MCPM - Model Context Protocol Manager

MCPM is an open source CLI tool for managing MCP servers. It provides a simplified global configuration approach where you install servers once and organize them with profiles, then integrate them into any MCP client. Features include server discovery through a central registry, direct execution, sharing capabilities, and client integration tools.

Demo is showing outdated v1 commands, new demo is baking ...

🤝 Community Contributions

💡 Grow the MCP ecosystem! We welcome contributions to our MCP Registry. Add your own servers, improve documentation, or suggest features. Open source thrives with community participation!

🚀 Quick Installation

🔎 Overview

MCPM v2.0 provides a simplified approach to managing MCP servers with a global configuration model. Key features include:

✨ Global Server Management: Install servers once, use everywhere
📋 Virtual Profiles: Organize servers with tags for different workflows
🔍 Server Discovery: Browse and install from the MCP Registry
🚀 Direct Execution: Run servers over stdio or HTTP for testing
🌐 Public Sharing: Share servers through secure tunnels
🎛️ Client Integration: Manage configurations for Claude Desktop, Cursor, Windsurf, and more
🤖 AI Agent Friendly: Non-interactive CLI with comprehensive automation support and llm.txt guide
💻 Beautiful CLI: Rich formatting and interactive interfaces
📊 Usage Analytics: Monitor server usage and performance

MCPM v2.0 eliminates the complexity of v1's target-based system in favor of a clean global workspace model.

🖥️ Supported MCP Clients

MCPM will support managing MCP servers for the following clients:

🤖 Claude Desktop (Anthropic)
⌨️ Cursor
🏄 Windsurf
🧩 Vscode
📝 Cline
➡️ Continue
🦢 Goose
🔥 5ire
🦘 Roo Code
✨ More clients coming soon...

🔥 Command Line Interface (CLI)

MCPM provides a comprehensive CLI with a clean, organized interface. The v2.0 architecture uses a global configuration model where servers are installed once and can be organized with profiles, then integrated into specific MCP clients as needed.

ℹ️ General

mcpm --help          # Display help information and available commands
mcpm --version       # Display the current version of MCPM

🌐 Server Management

Global server installation and management commands:

# 🔍 Search and Install
mcpm search [QUERY]           # Search the MCP Registry for available servers
mcpm info SERVER_NAME         # Display detailed information about a server
mcpm install SERVER_NAME      # Install a server from registry to global configuration
mcpm uninstall SERVER_NAME    # Remove a server from global configuration

# 📋 List and Inspect
mcpm ls                       # List all installed servers and their profile assignments
mcpm edit SERVER_NAME         # Edit a server configuration
mcpm inspect SERVER_NAME      # Launch MCP Inspector to test/debug a server

🚀 Server Execution

Execute servers directly for testing or integration:

mcpm run SERVER_NAME          # Execute a server directly over stdio
mcpm run SERVER_NAME --http   # Execute a server over HTTP for testing
mcpm share SERVER_NAME        # Share a server through secure tunnel for remote access
mcpm usage                    # Display comprehensive analytics and usage data

📂 Profile Management

Profiles are virtual tags that organize servers into logical groups for different workflows:

# 🔄 Profile Operations
mcpm profile ls               # List all profiles and their tagged servers
mcpm profile create PROFILE   # Create a new profile
mcpm profile rm PROFILE       # Remove a profile (servers remain installed)
mcpm profile edit PROFILE     # Interactive server selection for profile

# 🚀 Profile Execution
mcpm profile run PROFILE      # Execute all servers in a profile over stdio or HTTP
mcpm profile share PROFILE    # Share all servers in a profile through secure tunnel
mcpm profile inspect PROFILE  # Launch MCP Inspector for all servers in profile

🖥️ Client Integration

Manage MCP client configurations (Claude Desktop, Cursor, Windsurf, etc.):

mcpm client ls                 # List all supported MCP clients and their status
mcpm client edit CLIENT_NAME   # Interactive server enable/disable for a client
mcpm client edit CLIENT_NAME -e # Open client config in external editor
mcpm client import CLIENT_NAME  # Import server configurations from a client

🛠️ System & Configuration

mcpm doctor                   # Check system health and server status
mcpm config                   # Manage MCPM configuration and settings
mcpm migrate                  # Migrate from v1 to v2 configuration

📚 Registry

The MCP Registry is a central repository of available MCP servers that can be installed using MCPM. The registry is available at mcpm.sh/registry.

🤖 AI Agent Integration

MCPM is designed to be AI agent friendly with comprehensive automation support. Every interactive command has a non-interactive alternative using CLI parameters and environment variables.

🔧 Non-Interactive Mode

Set environment variables to enable full automation:

export MCPM_NON_INTERACTIVE=true  # Disable all interactive prompts
export MCPM_FORCE=true            # Skip confirmations
export MCPM_JSON_OUTPUT=true      # JSON output for parsing

📋 LLM.txt Guide

The llm.txt file provides comprehensive documentation specifically designed for AI agents, including:

Complete command reference with parameters and examples
Environment variable usage patterns
Best practices for automation
Error handling and troubleshooting
Batch operation patterns

The llm.txt file is automatically generated from the CLI structure and kept up-to-date with each release.

⚡ Example Usage

Use case 1: expose a local stdio server over HTTP

Add the server to MCPM

mcpm new [MY_SERVER_NAME] --type stdio --command "[COMMAND]" --args "[ARG_1] [ARG_2] ..."

(Add --force arg to bypass the confirmation interaction) Verify it appears in your installed servers:

mcpm ls

You should see [MY_SERVER_NAME] in the list.

Serve it over HTTP

mcpm run [MY_SERVER_NAME] --http

MCPM prints the server URL, for example:

URL: http://127.0.0.1:6276/mcp/

Expose it on your network (optional)

mcpm run [MY_SERVER_NAME] --http --host 0.0.0.0

Tip: add --port <PORT> to choose a different port.

Use case 2: combine multiple servers and serve them as one profile

Add the servers to MCPM

# Stdio server
mcpm new [SERVER_A] --type stdio --command "[COMMAND]" --args "[ARG_1] [ARG_2] ..." --force

# Remote HTTP/SSE server
mcpm new [SERVER_B] --type remote --url "http://SERVER_ADDR/mcp/" --force

Create a profile and add the servers Interactive:

mcpm profile create [PROFILE_NAME]
mcpm profile edit [PROFILE_NAME]

MCPM would list out all installed servers, you can use arrows to navigate, space to select/deselect, type to search, and Enter to confirm.

Verify:

mcpm profile ls

You should see your profile with the selected servers.

Run the profile

# Stdio
mcpm profile run [PROFILE_NAME]

# HTTP
mcpm profile run [PROFILE_NAME] --http

# Optional: host and port
mcpm profile run [PROFILE_NAME] --http --host 0.0.0.0 --port 8080

Other common usage

# Server management
mcpm new myserver --type stdio --command "python -m server" --force
mcpm edit myserver --env "API_KEY=secret" --force

# Profile management  
mcpm profile edit web-dev --add-server myserver --force
mcpm profile run web-dev --port 8080

# Client integration
mcpm client edit cursor --add-profile web-dev --force

🗺️ Roadmap

✅ v2.0 Complete

Global server configuration model
Profile-based server tagging and organization
Interactive command interfaces
Client integration management (mcpm client edit)
Modern CLI with consistent UX
Registry integration and server discovery
Direct server execution and sharing
Import from existing client configurations
Additional client support (gemini-cli, codex, etc.)

🔮 Future Enhancements

Advanced Server access monitoring and analytics
Execution in docker
Expose MCPM functionality as an MCP server (search, install, profile management etc.)
TUI interface for MCP inspect
TUI interface for MCP & profile management

📦 Other Installation Methods

🍺 Homebrew

brew install mcpm

📦 pipx (Recommended for Python tools)

pipx install mcpm

🪄 uv tool

uv tool install mcpm

More Installation Methods

🐍 pip

pip install mcpm

🧰 X-CMD

If you are a user of x-cmd, you can run:

x install mcpm.sh

👨‍💻 Development

This repository contains the CLI and service components for MCP Manager, built with Python and Click following modern package development practices.

📋 Development Requirements

🐍 Python 3.10+
🚀 uv (for virtual environment and dependency management)
🖱️ Click framework for CLI
✨ Rich for enhanced console output
🌐 Requests for API interactions

📁 Project Structure

The project follows the modern src-based layout:

mcpm.sh/
├── src/             # Source package directory
│   └── mcpm/        # Main package code
├── tests/           # Test directory
├── test_cli.py      # Development CLI runner
├── pyproject.toml   # Project configuration
├── pages/           # Website content
│   └── registry/    # Registry website
├── mcp-registry/    # MCP Registry data
└── README.md        # Documentation

🚀 Development Setup

Clone the repository

git clone https://github.com/pathintegral-institute/mcpm.sh.git
cd mcpm.sh

Set up a virtual environment with uv

uv venv --seed
source .venv/bin/activate  # On Unix/Mac

Install dependencies in development mode
```
uv pip install -e .
```

Run the CLI directly during development

# Either use the installed package
mcpm --help

# Or use the development script
./test_cli.py --help

Run tests
```
pytest tests/
```

✅ Best Practices

📁 Use the src-based directory structure to prevent import confusion
🔧 Develop with an editable install using uv pip install -e .
🧩 Keep commands modular in the src/mcpm/commands/ directory
🧪 Add tests for new functionality in the tests/ directory
💻 Use the test_cli.py script for quick development testing

🔢 Version Management

MCP uses a single source of truth pattern for version management to ensure consistency across all components.

🏷️ Version Structure

📍 The canonical version is defined in version.py at the project root
📥 src/mcpm/__init__.py imports this version
📄 pyproject.toml uses dynamic versioning to read from version.py
🏷️ Git tags are created with the same version number prefixed with 'v' (e.g., v1.0.0)

🔄 Updating the Version

When releasing a new version:

Use the provided version bump script

./bump_version.sh NEW_VERSION
# Example: ./bump_version.sh 1.1.0

Push the changes and tags
```
git push && git push --tags
```
Create a GitHub release matching the new version

This process ensures that the version is consistent in all places: code, package metadata, and git tags. PyPI release is handled by the CI/CD pipeline and will be triggered automatically.

📜 License

MIT

Features

Rate this server

Features

Rate this server