@khanglvm/mcpm

@khanglvm/mcpm

MCP Manager — Centralized MCP server configuration for AI coding agents.

Features

• Auto-detects AI coding agents
• Paste JSON/YAML/TOML MCP configs from READMEs
• Install from GitHub, GitLab, Bitbucket, Codeberg
• Keychain storage for secrets
• Sync registry to multiple agents at once
• Import existing servers from your agents

Core Concepts

Term	Description
Registry	Central store for all MCP server configs (~/.mcpm/registry.json)
Agents	AI coding tools (Claude Code, Cursor, Windsurf, etc.) that use MCP servers
Sync	Push configs from registry → agent config files
Import	Pull existing configs from agent config files → registry

For MCP Users

Manage MCP server configurations across your AI coding agents.

Quick Start

# Interactive mode (recommended)
npx @khanglvm/mcpm

# Or paste configuration
npx @khanglvm/mcpm --paste

CLI Commands

npx @khanglvm/mcpm                   # Interactive menu
npx @khanglvm/mcpm --paste           # Paste JSON/YAML/TOML configuration
npx @khanglvm/mcpm --build           # Build configuration step-by-step
npx @khanglvm/mcpm list              # List saved servers from registry
npx @khanglvm/mcpm add               # Add server interactively
npx @khanglvm/mcpm add <git-url>     # Add from Git URL
npx @khanglvm/mcpm sync              # Sync MCP servers from registry to agents
npx @khanglvm/mcpm import            # Import MCP configs from agents to registry
npx @khanglvm/mcpm status            # Check sync status
npx @khanglvm/mcpm remove <name>     # Remove MCP server

For MCP Developers

Help users install your MCP server with zero friction. Share one-liner install commands.

Option 1: Add mcp.json to Your Repository

Create mcp.json at your repository root. Users install with:

npx @khanglvm/mcpm https://github.com/you/my-server

Simple format — prompts user for all null values:

// mcp.json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@scope/my-server"],
      "env": {
        "API_KEY": null,           // → prompts user (masked, stored in keychain)
        "API_URL": null            // → prompts user
      }
    }
  }
}

Extended format — with descriptions, help links, and validation:

// mcp.json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@scope/my-server"],
      "env": {
        "API_KEY": {
          "value": null,
          "description": "Your API key from the dashboard",
          "note": "Get your API key at https://example.com/api-keys",
          "required": true,
          "hidden": true
        },
        "API_URL": {
          "value": "https://api.example.com",
          "description": "API endpoint (optional)",
          "required": false
        }
      }
    }
  }
}

Property	Type	Description
value	string | null	Default value, or null to prompt user
description	string	Hint displayed during setup
note	string	Developer note shown during setup (prefixed with "Note:")
required	boolean	Required field (default: true)
hidden	boolean	Mask input (auto-detected for key, secret, token, password)

HTTP/SSE transport — for remote MCP servers:

// mcp.json
{
  "mcpServers": {
    "remote-api": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": {
          "value": null,
          "description": "Bearer token from dashboard",
          "note": "Get your token at https://example.com/tokens",
          "hidden": true
        },
        "x-api-version": "2024-01"
      }
    }
  }
}

Option 2: Share a One-Liner Install Command

Extend the mcp.json config with CLI arguments — perfect for docs, READMEs, or Slack:

npx @khanglvm/mcpm https://github.com/you/my-server \
  --env:API_KEY=::description="Your API key"::note="Get from https://example.com/api-keys"::hidden \
  --env:API_URL=https://api.example.com::optional \
  --note:"Get API key at https://example.com/settings"

Modifier	Description
--env:KEY=VALUE	Pre-fill env var (overrides mcp.json)
--header:KEY=VALUE	Pre-fill header (for HTTP/SSE servers)
--agent:<name>	Pre-select agent(s) for installation
--scope:global / --scope:project	Pre-select installation scope (default: global)
-y / --yes	Automated install (validate, show tools, install to all agents)
::description="..."	Show hint during setup
::note="..."	Per-variable developer note (prefixed with "Note:")
::hidden	Mask input field
::optional	Allow empty value
--note:"..."	Display message to user

Auto mode (-y): Automatically validates MCP servers and installs to all compatible agents without prompts. Falls back to interactive mode if required credentials are missing.

All modifiers are optional. --env applies to stdio servers, --header applies to HTTP/SSE servers. --agent can be repeated (e.g., --agent:cursor --agent:claude-code).

Option 3: Share Inline Config (No Repository Needed)

Share a one-liner with embedded config — no mcp.json or repo required:

Simple (prompts for credentials):

npx @khanglvm/mcpm '{"github":{"command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_TOKEN":null}}}'

With helper text:

npx @khanglvm/mcpm '{"github":{"command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_TOKEN":{"value":null,"description":"Personal Access Token","note":"Create at https://github.com/settings/tokens"}}}}'

Auto-install (no prompts):

npx @khanglvm/mcpm '{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}' -y

From raw URL:

npx @khanglvm/mcpm https://raw.githubusercontent.com/you/repo/main/mcp.json

What Users See → Final Config

When a user runs either method:

• Prompts for missing values (with descriptions/hints)
• Masks sensitive fields (API_KEY)
• Offers keychain storage for secrets
• Saves to their AI agent's config:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@scope/my-server"],
      "env": {
        "API_KEY": "sk-abc123...",
        "API_URL": "https://api.example.com"
      }
    }
  }
}

Registry

All servers are stored in ~/.mcpm/registry.json and can be synced to any agent.

Location	Purpose
~/.mcpm/registry.json	Central server store
~/.mcpm/backups/	Automatic backups

Supported Agents

Agent	Transport	Format
Amazon Q Developer	stdio	JSON
Amp	stdio	JSON
Antigravity	stdio, http, sse	JSON
Claude Code	stdio, http, sse	JSON
Claude Desktop	stdio	JSON
Cline	stdio, http, sse	JSON
Codex (CLI / Desktop)	stdio	TOML
Continue	stdio, http	YAML
Cursor	stdio, http, sse	JSON
Factory Droid	stdio, http	JSON
Gemini CLI	stdio, http, sse	JSON
GitHub Copilot CLI	stdio, http	JSON
Goose	stdio, http	YAML
GitHub Copilot for JetBrains IDE	stdio, http	JSON
JetBrains AI Assistant	stdio	XML
OpenCode	stdio, http	YAML
Roo Code	stdio, http, sse	JSON
Sourcegraph Cody	stdio	JSON
VS Code + Copilot	stdio, http	JSON
Windsurf	stdio, http, sse	JSON
Zed	stdio	JSON

Changelog

v1.1.2

• fix: Sanitize server names containing spaces or special characters to valid identifiers (e.g., "Framelink MCP for Figma" → "Framelink_MCP_for_Figma").

v1.1.1

• fix: Support auto install flags (-a, -y) in inline config mode.
• docs: Add specific instruction to verify package name in README.

v1.1.0

• feat: Support --agent:all and -a flags for automated installation to all compatible agents.
• feat: Intelligent agent filtering based on transport (stdio/http/sse) and installation scope.

v1.0.2

• feat: Schema preservation in registry for credential reconfiguration.
• feat: "Reconfigure" option in sync flow to re-enter credentials from saved schema.
• refactor: Simplified credential prompt messages and note display.

v1.0.1

• feat: Direct JSON/YAML/TOML config data input support (paste config as CLI argument).
• feat: TOML format parsing for input configurations and README extraction.
• feat: Raw config URL support (fetch config directly from URLs like raw.githubusercontent.com).
• fix: Extended env schema now falls back to auto-detection for hidden field when not explicitly set.

v1.0.0

• feat: Format-aware centralized injector with native JSON, YAML, and TOML support.
• feat: Automatic OS keychain secret resolution during config injection.
• feat: Pre-install MCP server validation with available tools preview.
• feat: Consistent mcpm_ prefix enforcement across all agent configurations.
• feat: --agent: CLI argument for pre-selecting target agents.
• feat: -y / --yes auto-install mode with concise error summaries.
• refactor: Unified credential handling for stdio (env) and HTTP/SSE (headers) transports.

v0.1.7

• feat: Auto-inject -y flag for npx/pnpx commands during validation to prevent interactive prompts.
• test: Add unit tests for auto-execute flag injection.

v0.1.6

• feat: Add extended CLI arguments support (--env:KEY=VALUE, ::hidden, ::optional) for one-liner installations.
• docs: Comprehensive documentation updates for one-liner install commands.

v0.1.5

• feat: Add JetBrains AI Assistant support.
• style: Improve installation output formatting with grouped success messages.

v0.1.4

• feat: Add confirmation/edit step before installation.
• feat: Per-agent dynamic filtering for remote vs local transport.
• feat: Improved environment variable preview with smart masking.

v0.1.3

• fix: Ensure servers are saved to registry before agent injection.
• chore: Rename package to @khanglvm/mcpm.

v0.1.2

• feat: UX improvements (main menu loop, multiline paste).
• feat: Smart secret detection for environment variables.

v0.1.1

• feat: Initial release of mcpget (now mcpm).

License

MIT