MCPM: a global MCP server registry with profiles, and what its v2 model leaves out

Servers are installed once into a global configuration, not per client

The central idea in MCPM v2 is a global workspace. You install a server a single time, and every client you care about reads from that one pool. The commands for this are short:

mcpm search [QUERY]
mcpm info SERVER_NAME
mcpm install SERVER_NAME
mcpm uninstall SERVER_NAME
mcpm ls
mcpm edit SERVER_NAME

mcpm search queries the central MCP Registry, mcpm info shows details about one server, and mcpm install pulls a registry entry into the global configuration. mcpm ls lists everything installed together with its profile assignments, and mcpm edit opens a single server configuration for changes. The README's recommended way to get the tool itself is a one-line script, with brew, pipx and uv named as alternatives.

curl -sSL https://mcpm.sh/install | bash

The consequence of the global model is that a change to a server happens in one place. The cost is that the global configuration becomes the thing you have to trust: a bad edit there affects every client that has the server enabled. The project also ships a dedicated mcp-registry directory in the repository, which is where community server entries live, so the quality of what you can search for depends on what has been contributed there.

Profiles are tags on servers, so they group but do not isolate

A profile in MCPM is described as a virtual tag. Creating a profile does not copy servers or create a sandbox. It labels servers that are already installed, and removing a profile leaves those servers in place, as the command comment says: servers remain installed.

mcpm profile ls
mcpm profile create PROFILE
mcpm profile rm PROFILE
mcpm profile edit PROFILE
mcpm profile run PROFILE
mcpm profile share PROFILE
mcpm profile inspect PROFILE

mcpm profile edit gives an interactive server selection. mcpm profile run starts all the servers in a profile over stdio or HTTP, mcpm profile share exposes all of them through a secure tunnel, and mcpm profile inspect launches MCP Inspector against every server in the profile.

Because profiles are only tags, one server can sit in several profiles and there is no per-profile copy of its settings. If you want a work profile and a personal profile to run the same server with different credentials, the global model gives you one configuration for that server. The README does not describe per-profile overrides, so check mcpm edit SERVER_NAME and your actual servers before assuming you can split them.

Running a server directly: stdio by default, HTTP only as a testing mode

MCPM can execute an installed server without any client attached. The default transport is stdio, and an HTTP mode is offered for testing.

mcpm run SERVER_NAME
mcpm run SERVER_NAME --http
mcpm share SERVER_NAME
mcpm usage

This answers the common question of how to run an MCP server: install it with mcpm install, then call mcpm run with its name. The --http flag is labelled as being for testing, so it should not be read as a production deployment path. mcpm inspect SERVER_NAME launches MCP Inspector to test or debug a server, which is the better first stop when a server starts but misbehaves.

mcpm share puts a server behind a secure tunnel for remote access. The README does not say which tunnel provider is used or what authentication protects the public URL, so treat anything shared this way as reachable by whoever has the address until you have checked. mcpm usage prints usage analytics, and the dependency list includes duckdb, but the README does not state where that data is stored.

Client integration covers a named list, and the list is a promise rather than a guarantee

The README names ten clients: Claude Desktop, Cursor, Windsurf, Vscode, Cline, Continue, Goose, 5ire, Roo Code and OpenCode. It words this as MCPM will support managing servers for them, and adds that more clients are coming soon. A client outside that list has no first-class path.

mcpm client ls
mcpm client edit CLIENT_NAME
mcpm client edit CLIENT_NAME -e
mcpm client import CLIENT_NAME

mcpm client ls shows every supported client and its status, so it is the quickest way to find out whether your editor is actually recognised on your machine. mcpm client edit is an interactive screen for enabling and disabling servers for one client, while the -e flag opens that client's config file in an external editor for cases where you want to hand edit the JSON. mcpm client import reads the servers you already configured in a client and brings them into MCPM.

The import command matters for adoption. If you have been maintaining a Cursor or Claude Desktop configuration by hand, you do not have to retype it. The limit is that import goes in one direction per call and the README does not say how name clashes between an imported server and an installed one are resolved.

Updates only work for servers whose source MCPM has recorded

mcpm update tracks where each server came from, whether a git repository, an npm package or an HTTP remote, and pulls changes accordingly. The options are explicit:

mcpm update
mcpm update SERVER_NAME
mcpm update --check
mcpm update --rebase
mcpm update --init
mcpm update --init --force

--check applies nothing and only reports what would change. Git based servers are updated with git pull --ff-only by default, which means a local divergence makes the update fail rather than silently merge; --rebase is the opt-in alternative. NPX and UVX servers are different: they update themselves at runtime, so MCPM lists them for information only and does not drive their updates.

The --init flag is the part to remember when you have servers from before the update feature existed. It scans installed servers and fills in source metadata, and --init --force re-detects all of it. Without that metadata, MCPM has no recorded origin to pull from. The README names git-based, NPX and binary servers as updatable, but gives no detail on how a binary server is fetched, so test one before relying on it.

Automation mode is controlled by three environment variables

MCPM is written to be driven by scripts and AI agents as well as people. Every interactive command is said to have a non-interactive form using CLI parameters and environment variables, and three variables switch the behaviour globally.

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

MCPM_NON_INTERACTIVE removes prompts, so a command that would normally ask which servers to select must get its answer from parameters. MCPM_FORCE skips confirmations, which is convenient in CI and risky at a terminal, since mcpm uninstall or a profile removal will not stop to ask. MCPM_JSON_OUTPUT makes output parseable.

The repository root includes llm.txt, plus CLAUDE.md, GEMINI.md and QWEN.md. The README describes llm.txt as a guide for AI agents with a command reference, environment variable patterns and automation practices. That is the file to hand to an agent rather than the README. mcpm doctor checks system health and server status and is a sensible step to run in a script before anything else; mcpm config manages MCPM's own settings.

The v1 to v2 break left old tutorials and demos behind

MCPM v2.0 replaced the v1 target-based system with the global workspace model. The README admits that the demo still shows outdated v1 commands and that a new one is still being produced. Anyone following an older blog post or video is likely to be typing commands that no longer exist in the current CLI.

mcpm migrate
mcpm doctor
mcpm config

mcpm migrate converts a v1 configuration to v2. The repository also carries a MIGRATION_GUIDE.md at the top level, which is the place to read before running it on a machine with an existing setup, since the README gives only the command and one line of description.

The practical advice is to treat the README command list and mcpm --help as the source of truth, not any tutorial. The project releases through semantic-release, as the package.json devDependencies and the .releaserc.json file show, and CHANGELOG.md sits in the root. The latest tagged releases are v2.15.0 on 2026-05-22, v2.14.0 on 2026-03-27 and v2.13.0 on 2026-01-15, with the last push to the repository on 2026-10-25. The repository is not archived.

A Python 3.11 floor and a pinned fastmcp constrain where it installs cleanly

pyproject.toml sets requires-python to >=3.11 and builds with hatchling. The console script is mcpm, pointing at mcpm.cli:main. The dependency list contains two pins worth noticing: fastmcp is fixed at exactly 2.13.0, and pydantic is held to >=2.5.1 with an upper bound below 2.12.0.

The consequence is concrete. If you install MCPM into an environment that already has a newer pydantic, the resolver has to downgrade it or refuse. An exact fastmcp pin means other tools in the same environment that need a different fastmcp version will conflict. That is the reason the README offers pipx and uv among its install methods: they place the CLI in an isolated environment and avoid disturbing your project dependencies. The recommended script is the shortest path, but it runs a remote shell script, so read it first if that matters to you.

The rest of the dependency set is click, rich, rich-click, requests, mcp at 1.8.0 or newer, ruamel-yaml, watchfiles, duckdb, psutil, prompt-toolkit, deprecated, inquirerpy, rich-gradient, tomli, tomli-w and jsonschema. The license is MIT, and a flake.nix and README.nix.md exist for Nix users.

Editorial conclusion

MCPM suits developers who juggle MCP servers across several clients and want one install, one profile list and one update command. It is a poor fit if you need a v1 style per-target workflow, or if you cannot accept a Python 3.11 floor and an exact fastmcp pin. Before adopting it, run mcpm doctor on your machine and check mcpm client ls to confirm your client is on the supported list.

Frequently asked questions

Official sources

1. License: MIT
2. pathintegral-institute/mcpm.sh on GitHub
3. Project website
4. README
5. Releases