DEV Community

Trần Hoàng Tú
Trần Hoàng Tú

Posted on

How I Built mcpman — A Universal MCP Server Package Manager for 10+ AI IDEs

#typescript #opensource

When I first started working with the Model Context Protocol (MCP), I noticed something frustrating: each AI IDE had its own way of managing MCP servers. Claude Desktop had one config format, VS Code needed another, Cursor required yet another approach.

That's when I built mcpman — a universal package manager for MCP servers that works seamlessly across Claude, VS Code, Cursor, Windsurf, Zed, and 10+ other AI IDEs.

The Problem: MCP Configuration Chaos

The Model Context Protocol opened up incredible possibilities for AI-assisted development. But each IDE implemented MCP differently:

  • Claude Desktop uses a JSON config file in a specific directory
  • VS Code extensions need settings in settings.json
  • Cursor has its own configuration system
  • Windsurf, Zed, Codeium, Aider — all different

If you wanted to use the same MCP server across multiple IDEs, you'd manually find the right config file for each IDE, learn the specific format, keep them in sync, and debug inconsistencies.

Why I Built mcpman

The real catalyst came when I was helping a colleague set up multiple MCP servers. We spent 45 minutes just getting the configurations right.

That's when I asked: What if there was a single command-line tool that could install, manage, and update MCP servers across all IDEs at once?

# Install an MCP server once, and it works everywhere
mcpman install postgres-server

# List all installed servers
mcpman list

# Remove a server across all IDEs
mcpman uninstall postgres-server
Enter fullscreen mode Exit fullscreen mode

Architecture & Tech Decisions

Why TypeScript

  1. Cross-platform — Works on macOS, Linux, Windows
  2. IDE agnostic — Parse and write to different config formats
  3. Fast iteration — Mature ecosystem for file manipulation
  4. Familiar — Most developers using AI IDEs know JavaScript

The Core Architecture

mcpman is built around a few key concepts:

Config Adapters — Each IDE has an adapter that knows how to read/write its native config format.

Server Registry — A central registry of known MCP servers.

CLI Interface — Simple commands that delegate to the right adapter.

Sync Engine — Detects changes and propagates across IDEs.

┌─────────────────────────────────┐
│         CLI Commands            │
│  (install, list, uninstall)     │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│      mcpman Core Engine         │
│  (Config parsing, validation)   │
└────────────┬────────────────────┘
             │
    ┌────────┴────────┬─────────┬──────────┐
    │                 │         │          │
┌───▼────┐  ┌────┬────▼──┐  ┌──▼────┐  ┌─▼────┐
│ Claude │  │VS  │ Cursor │  │Zed    │  │...   │
│Desktop │  │Code│        │  │       │  │      │
└────────┘  └────┴────────┘  └───────┘  └──────┘
Enter fullscreen mode Exit fullscreen mode

Config Adapter Pattern

Each IDE gets its own adapter class:

interface ConfigAdapter {
  read(path: string): Promise<ServerConfig[]>;
  write(path: string, config: ServerConfig[]): Promise<void>;
  getConfigPath(): string;
}
Enter fullscreen mode Exit fullscreen mode

This means adding support for a new IDE = implementing one adapter class.

The Team Sync Feature

One of my favorite features — share configurations via a manifest file:

// mcpman.json in your project
{
  "servers": [
    {
      "name": "postgres-server",
      "source": "npm:mcpman-postgres"
    },
    {
      "name": "api-client",
      "source": "github:myorg/mcp-api-client"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Then anyone on your team runs:

mcpman sync
Enter fullscreen mode Exit fullscreen mode

Team MCP configuration in minutes instead of hours.

Lessons Learned

1. Fragmentation is Real — Every single IDE does things differently. This is both a pain point and an opportunity.

2. Testing Across Platforms is Hard — macOS, Windows, Linux all handle file paths differently. Docker helped a lot.

3. Backwards Compatibility Matters — Even early on, breaking changes hurt. Now mcpman auto-migrates old configs.

4. Documentation is Everything — First version had great features nobody knew about. I now spend equal time on docs and code.

What's Next

  • GUI for managing servers
  • Central repository of verified MCP servers
  • Server versioning and auto-updates
  • IDE plugin that shows available servers in your editor

Try mcpman 

npm install -g mcpman
mcpman list  # Detect your installed IDEs
Enter fullscreen mode Exit fullscreen mode

⭐ github.com/tranhoangtu-it/mcpman

I'm Trần Hoàng Tú, a full-stack developer from Vietnam building practical open-source tools. Check out my other projects:

Website: tuth.site | GitHub: @tranhoangtu-it

Top comments (0)