English | [简体中文](README.zh-CN.md)
```
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](mcp-registry/README.md). Add your own servers, improve documentation, or suggest features. Open source thrives with community participation!
## 🚀 Quick Installation
### Recommended:
```bash
curl -sSL https://mcpm.sh/install | bash
```
Or choose [other installation methods](#-other-installation-methods) like `brew`, `pipx`, `uv` etc.
## 🔎 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
- 💻 **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
```bash
mcpm --help # Display help information and available commands
mcpm --version # Display the current version of MCPM
```
### 🌐 Server Management
Global server installation and management commands:
```bash
# 🔍 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:
```bash
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:
```bash
# 🔄 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.):
```bash
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
```bash
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](https://mcpm.sh/registry).
## 🗺️ Roadmap
### ✅ v2.0 Complete
- [x] Global server configuration model
- [x] Profile-based server tagging and organization
- [x] Interactive command interfaces
- [x] Client integration management (`mcpm client edit`)
- [x] Modern CLI with consistent UX
- [x] Registry integration and server discovery
- [x] Direct server execution and sharing
- [x] Import from existing client configurations
### 🔮 Future Enhancements
- [ ] Advanced Server access monitoring and analytics
- [ ] Additional client support (gemini-cli, codex, etc.)
- [ ] Execution in docker
## 📦 Other Installation Methods
### 🍺 Homebrew
```bash
brew install mcpm
```
### 📦 pipx (Recommended for Python tools)
```bash
pipx install mcpm
```
### 🪄 uv tool
```bash
uv tool install mcpm
```
## More Installation Methods
### 🐍 pip
```bash
pip install mcpm
```
### 🧰 X-CMD
If you are a user of [x-cmd](https://x-cmd.com), you can run:
```sh
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
1. Clone the repository
```
git clone https://github.com/pathintegral-institute/mcpm.sh.git
cd mcpm.sh
```
2. Set up a virtual environment with uv
```
uv venv --seed
source .venv/bin/activate # On Unix/Mac
```
3. Install dependencies in development mode
```
uv pip install -e .
```
4. Run the CLI directly during development
```
# Either use the installed package
mcpm --help
# Or use the development script
./test_cli.py --help
```
5. 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:
1. Use the provided version bump script
```
./bump_version.sh NEW_VERSION
# Example: ./bump_version.sh 1.1.0
```
2. Push the changes and tags
```
git push && git push --tags
```
3. 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
## Star History
[](https://www.star-history.com/#pathintegral-institute/mcpm.sh&Date)
Raw data
{
"_id": null,
"home_page": null,
"name": "mcpm",
"maintainer": "Path Integral Institute",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "Claude Desktop, Cursor, MCP, MCPM, Model Context Protocol, Windsurf",
"author": "MCPM Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/09/c9/9dd8fb1aac1bd75f00723e97426a029503e148e36f8b1ff3b90b45ae013d/mcpm-2.5.0.tar.gz",
"platform": null,
"description": "\n\n\n\n\n\n\n\nEnglish | [\u7b80\u4f53\u4e2d\u6587](README.zh-CN.md)\n\n\n\n```\nOpen Source. Forever Free.\nBuilt with \u2764\ufe0f by Path Integral Institute\n```\n\n# \ud83c\udf1f MCPM - Model Context Protocol Manager\n\nMCPM 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.\n\nDemo is showing outdated v1 commands, new demo is baking ...\n\n\n## \ud83e\udd1d Community Contributions\n\n> \ud83d\udca1 **Grow the MCP ecosystem!** We welcome contributions to our [MCP Registry](mcp-registry/README.md). Add your own servers, improve documentation, or suggest features. Open source thrives with community participation!\n\n## \ud83d\ude80 Quick Installation\n\n### Recommended: \n\n```bash\ncurl -sSL https://mcpm.sh/install | bash\n```\n\nOr choose [other installation methods](#-other-installation-methods) like `brew`, `pipx`, `uv` etc.\n\n## \ud83d\udd0e Overview\n\nMCPM v2.0 provides a simplified approach to managing MCP servers with a global configuration model. Key features include:\n\n- \u2728 **Global Server Management**: Install servers once, use everywhere\n- \ud83d\udccb **Virtual Profiles**: Organize servers with tags for different workflows \n- \ud83d\udd0d **Server Discovery**: Browse and install from the MCP Registry\n- \ud83d\ude80 **Direct Execution**: Run servers over stdio or HTTP for testing\n- \ud83c\udf10 **Public Sharing**: Share servers through secure tunnels\n- \ud83c\udf9b\ufe0f **Client Integration**: Manage configurations for Claude Desktop, Cursor, Windsurf, and more\n- \ud83d\udcbb **Beautiful CLI**: Rich formatting and interactive interfaces\n- \ud83d\udcca **Usage Analytics**: Monitor server usage and performance\n\nMCPM v2.0 eliminates the complexity of v1's target-based system in favor of a clean global workspace model.\n\n## \ud83d\udda5\ufe0f Supported MCP Clients\n\nMCPM will support managing MCP servers for the following clients:\n\n- \ud83e\udd16 Claude Desktop (Anthropic)\n- \u2328\ufe0f Cursor\n- \ud83c\udfc4 Windsurf\n- \ud83e\udde9 Vscode\n- \ud83d\udcdd Cline\n- \u27a1\ufe0f Continue\n- \ud83e\udda2 Goose\n- \ud83d\udd25 5ire\n- \ud83e\udd98 Roo Code\n- \u2728 More clients coming soon...\n\n## \ud83d\udd25 Command Line Interface (CLI)\n\nMCPM 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.\n\n### \u2139\ufe0f General\n\n```bash\nmcpm --help # Display help information and available commands\nmcpm --version # Display the current version of MCPM\n```\n\n### \ud83c\udf10 Server Management\n\nGlobal server installation and management commands:\n\n```bash\n# \ud83d\udd0d Search and Install\nmcpm search [QUERY] # Search the MCP Registry for available servers\nmcpm info SERVER_NAME # Display detailed information about a server\nmcpm install SERVER_NAME # Install a server from registry to global configuration\nmcpm uninstall SERVER_NAME # Remove a server from global configuration\n\n# \ud83d\udccb List and Inspect\nmcpm ls # List all installed servers and their profile assignments\nmcpm edit SERVER_NAME # Edit a server configuration\nmcpm inspect SERVER_NAME # Launch MCP Inspector to test/debug a server\n```\n\n### \ud83d\ude80 Server Execution\n\nExecute servers directly for testing or integration:\n\n```bash\nmcpm run SERVER_NAME # Execute a server directly over stdio\nmcpm run SERVER_NAME --http # Execute a server over HTTP for testing\nmcpm share SERVER_NAME # Share a server through secure tunnel for remote access\nmcpm usage # Display comprehensive analytics and usage data\n```\n\n### \ud83d\udcc2 Profile Management\n\nProfiles are virtual tags that organize servers into logical groups for different workflows:\n\n```bash\n# \ud83d\udd04 Profile Operations\nmcpm profile ls # List all profiles and their tagged servers\nmcpm profile create PROFILE # Create a new profile\nmcpm profile rm PROFILE # Remove a profile (servers remain installed)\nmcpm profile edit PROFILE # Interactive server selection for profile\n\n# \ud83d\ude80 Profile Execution\nmcpm profile run PROFILE # Execute all servers in a profile over stdio or HTTP\nmcpm profile share PROFILE # Share all servers in a profile through secure tunnel\nmcpm profile inspect PROFILE # Launch MCP Inspector for all servers in profile\n```\n\n### \ud83d\udda5\ufe0f Client Integration\n\nManage MCP client configurations (Claude Desktop, Cursor, Windsurf, etc.):\n\n```bash\nmcpm client ls # List all supported MCP clients and their status\nmcpm client edit CLIENT_NAME # Interactive server enable/disable for a client\nmcpm client edit CLIENT_NAME -e # Open client config in external editor\nmcpm client import CLIENT_NAME # Import server configurations from a client\n```\n\n### \ud83d\udee0\ufe0f System & Configuration\n\n```bash\nmcpm doctor # Check system health and server status\nmcpm config # Manage MCPM configuration and settings\nmcpm migrate # Migrate from v1 to v2 configuration\n```\n\n### \ud83d\udcda Registry\n\nThe MCP Registry is a central repository of available MCP servers that can be installed using MCPM. The registry is available at [mcpm.sh/registry](https://mcpm.sh/registry).\n\n## \ud83d\uddfa\ufe0f Roadmap\n\n### \u2705 v2.0 Complete\n- [x] Global server configuration model\n- [x] Profile-based server tagging and organization \n- [x] Interactive command interfaces\n- [x] Client integration management (`mcpm client edit`)\n- [x] Modern CLI with consistent UX\n- [x] Registry integration and server discovery\n- [x] Direct server execution and sharing\n- [x] Import from existing client configurations\n\n### \ud83d\udd2e Future Enhancements\n- [ ] Advanced Server access monitoring and analytics\n- [ ] Additional client support (gemini-cli, codex, etc.)\n- [ ] Execution in docker\n\n\n## \ud83d\udce6 Other Installation Methods\n\n### \ud83c\udf7a Homebrew\n\n```bash\nbrew install mcpm\n```\n\n### \ud83d\udce6 pipx (Recommended for Python tools)\n\n```bash\npipx install mcpm\n```\n\n### \ud83e\ude84 uv tool\n\n```bash\nuv tool install mcpm\n```\n\n## More Installation Methods\n\n### \ud83d\udc0d pip\n\n```bash\npip install mcpm\n```\n\n### \ud83e\uddf0 X-CMD\n\nIf you are a user of [x-cmd](https://x-cmd.com), you can run:\n\n```sh\nx install mcpm.sh\n```\n\n\n## \ud83d\udc68\u200d\ud83d\udcbb Development\n\nThis repository contains the CLI and service components for MCP Manager, built with Python and Click following modern package development practices.\n\n### \ud83d\udccb Development Requirements\n\n- \ud83d\udc0d Python 3.10+\n- \ud83d\ude80 uv (for virtual environment and dependency management)\n- \ud83d\uddb1\ufe0f Click framework for CLI\n- \u2728 Rich for enhanced console output\n- \ud83c\udf10 Requests for API interactions\n\n### \ud83d\udcc1 Project Structure\n\nThe project follows the modern src-based layout:\n\n```\nmcpm.sh/\n\u251c\u2500\u2500 src/ # Source package directory\n\u2502 \u2514\u2500\u2500 mcpm/ # Main package code\n\u251c\u2500\u2500 tests/ # Test directory\n\u251c\u2500\u2500 test_cli.py # Development CLI runner\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 pages/ # Website content\n\u2502 \u2514\u2500\u2500 registry/ # Registry website\n\u251c\u2500\u2500 mcp-registry/ # MCP Registry data\n\u2514\u2500\u2500 README.md # Documentation\n```\n\n### \ud83d\ude80 Development Setup\n\n1. Clone the repository\n ```\n git clone https://github.com/pathintegral-institute/mcpm.sh.git\n cd mcpm.sh\n ```\n\n2. Set up a virtual environment with uv\n ```\n uv venv --seed\n source .venv/bin/activate # On Unix/Mac\n ```\n\n3. Install dependencies in development mode\n ```\n uv pip install -e .\n ```\n\n4. Run the CLI directly during development\n ```\n # Either use the installed package\n mcpm --help\n\n # Or use the development script\n ./test_cli.py --help\n ```\n\n5. Run tests\n ```\n pytest tests/\n ```\n\n### \u2705 Best Practices\n\n- \ud83d\udcc1 Use the src-based directory structure to prevent import confusion\n- \ud83d\udd27 Develop with an editable install using `uv pip install -e .`\n- \ud83e\udde9 Keep commands modular in the `src/mcpm/commands/` directory\n- \ud83e\uddea Add tests for new functionality in the `tests/` directory\n- \ud83d\udcbb Use the `test_cli.py` script for quick development testing\n\n\n### \ud83d\udd22 Version Management\n\nMCP uses a single source of truth pattern for version management to ensure consistency across all components.\n\n#### \ud83c\udff7\ufe0f Version Structure\n\n- \ud83d\udccd The canonical version is defined in `version.py` at the project root\n- \ud83d\udce5 `src/mcpm/__init__.py` imports this version\n- \ud83d\udcc4 `pyproject.toml` uses dynamic versioning to read from `version.py`\n- \ud83c\udff7\ufe0f Git tags are created with the same version number prefixed with 'v' (e.g., v1.0.0)\n\n#### \ud83d\udd04 Updating the Version\n\nWhen releasing a new version:\n\n1. Use the provided version bump script\n ```\n ./bump_version.sh NEW_VERSION\n # Example: ./bump_version.sh 1.1.0\n ```\n\n2. Push the changes and tags\n ```\n git push && git push --tags\n ```\n\n3. Create a GitHub release matching the new version\n\nThis process ensures that the version is consistent in all places: code, package metadata, and git tags.\nPyPI release is handled by the CI/CD pipeline and will be triggered automatically.\n\n## \ud83d\udcdc License\n\nMIT\n\n\n## Star History\n\n[](https://www.star-history.com/#pathintegral-institute/mcpm.sh&Date)",
"bugtrack_url": null,
"license": null,
"summary": "MCPM - Model Context Protocol Manager",
"version": "2.5.0",
"project_urls": {
"Homepage": "https://mcpm.sh",
"Issues": "https://github.com/pathintegral-institute/mcpm.sh/issues",
"Repository": "https://github.com/pathintegral-institute/mcpm.sh"
},
"split_keywords": [
"claude desktop",
" cursor",
" mcp",
" mcpm",
" model context protocol",
" windsurf"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b06d0996917eed6294bf47795270959c0a1d20f17e48d9132be4877ed7d9abca",
"md5": "d03bf13689e05160edbed54542054286",
"sha256": "ca038b63e38ad70f5c6dffcd7f7da31deef002b57d6ad0225648c814526013f6"
},
"downloads": -1,
"filename": "mcpm-2.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d03bf13689e05160edbed54542054286",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 134956,
"upload_time": "2025-07-14T02:59:59",
"upload_time_iso_8601": "2025-07-14T02:59:59.513812Z",
"url": "https://files.pythonhosted.org/packages/b0/6d/0996917eed6294bf47795270959c0a1d20f17e48d9132be4877ed7d9abca/mcpm-2.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "09c99dd8fb1aac1bd75f00723e97426a029503e148e36f8b1ff3b90b45ae013d",
"md5": "4e9779bb7b9f7a35c7dad9b4e7520d0e",
"sha256": "81f5093a7eb8d7dcc2900e948fd95dc958aba2f4734bd67e2993d26a48a407eb"
},
"downloads": -1,
"filename": "mcpm-2.5.0.tar.gz",
"has_sig": false,
"md5_digest": "4e9779bb7b9f7a35c7dad9b4e7520d0e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 1883299,
"upload_time": "2025-07-14T03:00:01",
"upload_time_iso_8601": "2025-07-14T03:00:01.186153Z",
"url": "https://files.pythonhosted.org/packages/09/c9/9dd8fb1aac1bd75f00723e97426a029503e148e36f8b1ff3b90b45ae013d/mcpm-2.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 03:00:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pathintegral-institute",
"github_project": "mcpm.sh",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mcpm"
}
JSON
