mcpcm

███╗   ███╗ ██████╗██████╗  ██████╗███╗   ███╗
████╗ ████║██╔════╝██╔══██╗██╔════╝████╗ ████║
██╔████╔██║██║     ██████╔╝██║     ██╔████╔██║
██║╚██╔╝██║██║     ██╔═══╝ ██║     ██║╚██╔╝██║
██║ ╚═╝ ██║╚██████╗██║     ╚██████╗██║ ╚═╝ ██║
╚═╝     ╚═╝ ╚═════╝╚═╝      ╚═════╝╚═╝     ╚═╝

MCP Configuration Manager - Manage MCP server configurations across AI Agents.

Supports Cursor, Claude Code, Antigravity, Windsurf, VS Code, and 6 more.

Installation

# Use directly with npx (no install required)
npx mcpcm --help

# Or install globally
npm install -g mcpcm

Quick Start

# Add MCP server to specific agent
npx mcpcm add '{"mcpServers":{"my-server":{"command":"node","args":["/path/to/server"]}}}' --agent cursor

# Add from file to all installed agents
npx mcpcm add --file mcp.json --global

# List all configured MCP servers
npx mcpcm list

Commands

| Command | Description | | -------------- | ---------------------------------------------------- | | mcpcm add | Add new MCP servers (skips existing) | | mcpcm update | Update existing MCP servers (skips non-existing) | | mcpcm del | Delete MCP servers (skips non-existing) | | mcpcm list | List all MCP configurations | | mcpcm find | Find where an MCP server is configured | | mcpcm sync | Full sync from one agent to others (overwrites) |

Common Options

These options are shared across multiple commands:

| Option | Applies to | Description | | ------------------------- | ---------------------- | ----------------------------------------------- | | -a, --agent <agents...> | add, update, del, list | Target specific agent(s) | | -g, --global | add, update, del, list | Apply to global configs of all installed agents | | -w, --workspace | add, update, del, list | Apply to project-level configs | | -f, --file <path> | add, update | Read config from file instead of JSON string | | -v, --verbose | all | Show detailed output |

[!TIP] You must specify one of --agent, --global, or --workspace to indicate where to apply the operation.

Add Command

Add new MCP servers to agent configurations.

# From JSON string
npx mcpcm add '{"mcpServers":{"easeim":{"command":"node","args":["/path/to/index.js"]}}}' --agent cursor

# From file to all installed agents
npx mcpcm add --file mcp.json --global

# To current project
npx mcpcm add --file mcp.json --workspace

[!NOTE] If a server already exists, it will be skipped (not overwritten). Use mcpcm update to modify existing servers.

Update Command

Update existing MCP server configurations.

# Update specific server in an agent
npx mcpcm update '{"mcpServers":{"my-server":{"args":["/new/path"]}}}' --agent cursor

# Update from file
npx mcpcm update --file mcp.json --global

[!NOTE] Only existing servers will be updated. Non-existing servers are skipped. Use mcpcm add to add new servers.

Delete Command

Delete MCP servers from configurations.

# From specific agent
npx mcpcm del my-server --agent cursor

# From all agents
npx mcpcm del my-server --global

# From project configs
npx mcpcm del my-server --workspace

[!NOTE] Only existing servers will be deleted. Non-existing servers are skipped with a warning.

List Command

List all configured MCP servers.

# All configs
npx mcpcm list

# Specific agent
npx mcpcm list --agent cursor

# Global configs only
npx mcpcm list --global

# Project configs only
npx mcpcm list --workspace

Find Command

Search for an MCP server across all configurations.

npx mcpcm find easeim

# Output:
# ✓ easeim found in:
#   Cursor (global): ~/.cursor/mcp.json
#   Claude Code (project): .mcp.json

Sync Command

Synchronize MCP configurations from one agent to others.

# Sync to specific agents
npx mcpcm sync --from cursor --to antigravity claude-code

# Sync to all installed agents
npx mcpcm sync --from cursor --to-all

[!IMPORTANT] Sync performs a full synchronization: existing servers are overwritten, and new servers are added. This is different from add which skips existing servers.

Supported Agents

| Agent | --agent | Project Config | Global Config | | ------------------------ | ------------- | --------------------------- | -------------------------------------------------- | | Cursor | cursor | .cursor/mcp.json | ~/.cursor/mcp.json | | Claude Code | claude-code | .mcp.json | ~/.claude.json | | Antigravity | antigravity | .gemini/mcp_config.json | ~/.gemini/antigravity/mcp_config.json | | Windsurf | windsurf | .windsurf/mcp_config.json | ~/.codeium/windsurf/mcp_config.json | | VS Code / GitHub Copilot | vscode | .vscode/mcp.json | ~/Library/Application Support/Code/User/mcp.json | | Codex | codex | .codex/config.toml | ~/.codex/config.toml | | OpenCode | opencode | - | ~/.config/opencode/opencode.json | | Gemini CLI | gemini-cli | .gemini/settings.json | ~/.gemini/settings.json | | Qoder | qoder | - | (managed via qodercli) | | Qwen Code | qwen-code | .qwen/settings.json | ~/.qwen/settings.json | | Trae | trae | .trae/mcp.json | - |

[!NOTE]

• Claude Code uses ~/.claude.json (not ~/.claude/ directory) for global config
• VS Code path varies by OS (shown above is macOS)
• Some agents don't support project-level or global configs (marked with -)

MCP Configuration Format

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["/path/to/server/index.js"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Examples

Add multiple servers from file

Create mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

Then:

# Add to all installed agents
npx mcpcm add --file mcp.json --global

# Or add to current project for team sharing
npx mcpcm add --file mcp.json --workspace

Sync development environment

# Set up Cursor with all your MCP servers
# Then sync to other agents
npx mcpcm sync --from cursor --to-all

Configuration Priority

When agents have multiple config sources:

Project > Editor > Global

Project configs take precedence over global configs.

Recommended .gitignore

If you're using mcpcm in a project, add the following to your .gitignore to exclude agent config directories created during testing:

# MCP Configuration files (created during testing)
.cursor/
.mcp.json
.gemini/
.windsurf/
.vscode/
.codex/
.qwen/
.trae/

Troubleshooting

"No installed agents detected"

The CLI auto-detects installed agents by checking for config directories. If none are found:

• Ensure at least one supported agent is installed
• Use --agent to explicitly specify target agents

Config not taking effect

• Restart the AI agent after modifying configs
• Check the config file format (JSON vs TOML for Codex)
• Verify the command path is correct and executable

Permission errors

Ensure you have write access to the config directory.

Custom Agent Configuration

You can add or modify AI Agent configurations by editing the agents object in the installed CLI file.

Locate the CLI File

# Find the global installation path
npm root -g
# Then edit: <npm_root>/mcpcm/dist/cli.js

Modify the agents Object

Open dist/cli.js and locate the agents object (around line 27). Add or modify agent entries:

var agents = {
  // ... existing agents ...

  // Add your custom agent:
  'my-agent': {
    name: 'my-agent',
    displayName: 'My Custom Agent',
    projectConfigPath: '.my-agent/mcp.json', // or null if not supported
    globalConfigPath: join(home, '.my-agent/mcp.json'),
    configFormat: 'json', // 'json' or 'toml'
    mcpConfigKey: 'mcpServers', // key in config file
    detectInstalled: async () => existsSync(join(home, '.my-agent')),
  },
};

Configuration Fields

| Field | Description | | ------------------- | ----------------------------------------------------- | | name | Agent identifier (used in --agent option) | | displayName | Human-readable name shown in output | | projectConfigPath | Relative path for project config (or null) | | globalConfigPath | Absolute path for global config (or null) | | configFormat | Config file format: 'json' or 'toml' | | mcpConfigKey | Key for MCP servers in config (e.g., 'mcpServers') | | detectInstalled | Async function returning true if agent is installed |

[!NOTE] Changes take effect immediately. No rebuild required.

[!WARNING] Reinstalling or updating the package will overwrite your changes.

[!TIP] If you find this method cumbersome, consider submitting a PR to add official support for your agent!

License

MIT

References

skills