Content







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
- 🤖 **AI Agent Friendly**: Non-interactive CLI with comprehensive automation support and [llm.txt](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
```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).
## 🤖 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:
```bash
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](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
1) Add the server to MCPM
```bash
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:
```bash
mcpm ls
```
You should see `[MY_SERVER_NAME]` in the list.
2) Serve it over HTTP
```bash
mcpm run [MY_SERVER_NAME] --http
```
MCPM prints the server URL, for example:
```
URL: http://127.0.0.1:6276/mcp/
```
3) Expose it on your network (optional)
```bash
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
1) Add the servers to MCPM
```bash
# 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
```
2) Create a profile and add the servers
Interactive:
```bash
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:
```bash
mcpm profile ls
```
You should see your profile with the selected servers.
3) Run the profile
```bash
# 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
```bash
# 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
- [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
- [x] 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
```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)
Connection Info
You Might Also Like
MarkItDown MCP
Converting files and office documents to Markdown.
Time
Obtaining current time information and converting time between different...
Filesystem
Model Context Protocol Servers
Sequential Thinking
Offers a structured approach to dynamic and reflective problem-solving,...
Git
Model Context Protocol Servers
Context 7
Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors