I built the missing package manager for MCP servers

If you use Claude Desktop, Cursor, VS Code, or Windsurf with MCP servers, you know the pain: manually editing JSON config files, each client storing configs differently, no way to know if a server is healthy, and no version pinning.

I built mcpman to fix this.

## What is MCP?

Model Context Protocol (MCP) is Anthropic's open standard that lets AI assistants connect to external tools and data sources. Think of MCP servers as plugins for your AI coding assistant.

The problem? Installing and managing these servers is still manual and fragmented.

## The gap nobody filled

I researched every existing tool:

| Tool | Focus | Limitation |
|------|-------|-----------|
| Smithery CLI | Registry | Claude-only, no health checks |
| mcpm.sh | Config editing | Limited multi-client, no lockfile |
| mcp-get | Package install | Dead (redirected to Smithery) |

Nobody owned the operational layer — health monitoring, version pinning, cross-client sync, reproducible setups.

## Enter mcpman

sh
  # Install an MCP server across all your AI clients
  npx mcpman install @modelcontextprotocol/server-filesystem

  # See what's installed with health status
  npx mcpman list

  # Run diagnostics
  npx mcpman doctor

  # Reproducible team setup
  npx mcpman init

  What it does

  - install <server> — resolves from npm, Smithery, or GitHub. Auto-detects installed clients and configures them all.
  - list — shows every installed server with health indicators (green/yellow/red).
  - doctor — runs 4-layer diagnostics: runtime check, env var validation, process spawn, MCP JSON-RPC handshake.
  - remove — clean uninstall from all clients at once.
  - init — creates mcpman.lock for reproducible team setups. Share your MCP config like you share package-lock.json.

  Multi-client support

  mcpman manages configs for all 4 major AI clients:

  - Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
  - Cursor — ~/.cursor/mcp.json
  - VS Code — workspace .vscode/settings.json
  - Windsurf — ~/.codeium/windsurf/mcp_config.json

  One mcpman install writes to all of them.

  Architecture

  Built with TypeScript and these focused libraries:

  - citty — declarative CLI framework (zero boilerplate)
  - @clack/prompts — beautiful interactive UX
  - picocolors — terminal colors (3x smaller than chalk)
  - nanospinner — progress spinners

  The entire CLI is ~45KB bundled. No daemon, no background process.

  The doctor is in

  My favorite feature. mcpman doctor runs parallel health checks:

  1. Runtime check — is node/python/uvx installed?
  2. Env var validation — are required API keys set?
  3. Process spawn — does the server binary actually start?
  4. MCP handshake — does it respond to initialize JSON-RPC?

  npx mcpman doctor

    ✓ server-filesystem    healthy
    ⚠ server-github        missing GITHUB_TOKEN
    ✗ server-slack         process crashed

  Try it

  npm install -g mcpman
  # or just use npx
  npx mcpman install @modelcontextprotocol/server-filesystem

  59 tests passing. MIT licensed. Contributions welcome.

  GitHub: github.com/tranhoangtu-it/mcpman
  npm: npmjs.com/package/mcpman

  What's next (v0.2)

  - Encrypted credential management (no more API keys in JSON)
  - Cross-client config sync
  - Security scanning + trust scoring
  - Auto-update notifications

  ---
  What MCP server management pain points have you hit? I'd love to hear your feedback.