ccmcp

A CLI tool for managing MCP (Model Context Protocol) servers used by Claude Code. It maintains a central registry at ~/.ccmcp/config.json as the source of truth, and lets you link/unlink servers into Claude Code's config per-project or globally — without ever touching entries you didn't add.

How it works

ccmcp keeps its own registry (~/.ccmcp/config.json) separate from Claude Code's config (~/.claude.json). You manage servers in the registry, then sync them into Claude Code's config with ccmcp sync or ccmcp link. Only entries that ccmcp owns are ever modified; servers you added manually in Claude Code are left untouched.

Servers in the registry can be kept disabled — they exist in the registry but are not written to Claude Code's config until you enable them. This lets you store server configs you don't always need and toggle them on or off with ccmcp update <name> --enable true/false followed by ccmcp sync.

Installation

One-line install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/iambpn/ccmcp/main/scripts/install.sh | bash

This downloads the latest release binary, verifies its checksum, and installs it to ~/.local/bin/ccmcp.

If ~/.local/bin is not in your PATH, the installer will tell you exactly what to add to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Uninstall

curl -fsSL https://raw.githubusercontent.com/iambpn/ccmcp/main/scripts/install.sh | bash -s -- --uninstall

Windows

Download the latest ccmcp-win.exe from the Releases page and place it somewhere on your PATH.

Commands

ccmcp add <name> [commandOrUrl] [args...]

Add an MCP server to the registry. The syntax mirrors claude mcp add, so the same command you'd give Claude Code works here — you just add it to ccmcp's registry instead of writing straight into Claude Code's config.

# stdio server (Claude Code style — command goes after `--`)
ccmcp add my-server -- npx my-mcp-pkg

# stdio server with environment variables
ccmcp add my-server -e API_KEY=abc123 -e DEBUG=true -- npx my-mcp-pkg

# HTTP server
ccmcp add --transport http sentry https://mcp.sentry.dev/mcp

# HTTP server with a header
ccmcp add corridor --transport http https://app.corridor.dev/api/mcp \
  -H "Authorization: Bearer abc123"

# Add it already enabled (still run `ccmcp sync` to write it to Claude Code)
ccmcp add my-server --enabled -- npx my-mcp-pkg

# Raw JSON config (or use `ccmcp add-json` below)
ccmcp add my-server --json '{"type":"stdio","command":"npx","args":["my-pkg"]}'

Options:

Option	Description
[commandOrUrl] [args...]	Positional command (stdio) or URL (http/sse/ws); put a stdio command after --
-t, --transport <type>	stdio, http, sse, or ws (defaults to stdio)
-e, --env <KEY=VALUE...>	Environment variable (repeatable)
-H, --header <"Key: Value"...>	HTTP header (repeatable)
-s, --scope <scope>	local, user, or project — Claude Code's names (global is an alias for user). Default: local
--project <path...>	Project paths for project/local-scoped servers (omit to leave unlinked)
--json <json>	Raw server config as JSON
--enabled	Mark the server enabled in the registry (run ccmcp sync to apply)
--command, --args, --url	Legacy flags, kept for backward compatibility

Scope mapping. Claude Code has three scopes (local, user, project); ccmcp stores two. user maps to ccmcp's global (Claude Code's user config), while local and project both map to ccmcp's project scope. All of Claude Code's names are accepted so you can copy commands verbatim.

---

ccmcp add-json <name> <json>

Add a server from a JSON string — the counterpart to claude mcp add-json.

ccmcp add-json weather '{"type":"stdio","command":"weather-cli","args":["--api-key","KEY"]}'

Accepts the same --scope, --project, and --enabled options as add.

---

ccmcp list (alias: ls)

List all servers in the registry with their status.

ccmcp list

Output shows name, scope, enabled status, and which locations each server has been deployed to.

---

ccmcp get <name>

Show the full config for a single server.

ccmcp get my-server

---

ccmcp update <name>

Update a server's enabled state or scope.

# Enable a server
ccmcp update my-server --enable true

# Disable a server
ccmcp update my-server --enable false

# Change to global scope (`--scope user` also works)
ccmcp update my-server --scope global

# Change to project scope for a specific project (`--scope local` also works)
ccmcp update my-server --scope project --project /path/to/project

---

ccmcp link <name>

Write a single server from the registry into Claude Code's config for the current project (or globally, if the server is global-scoped).

ccmcp link my-server

---

ccmcp unlink <name>

Remove a single server from Claude Code's config.

ccmcp unlink my-server

---

ccmcp sync

Reconcile the entire registry into Claude Code's config. Enabled servers are written; disabled servers are removed — except locations you explicitly attached with ccmcp link, which stick around until you ccmcp unlink them or drop that project from the server's scope. Only entries previously written by ccmcp are touched.

ccmcp sync

Run this after changing multiple servers or after editing the registry manually.

---

ccmcp remove <name> (alias: rm)

Remove a server from the registry entirely.

ccmcp remove my-server

---

ccmcp import

Import MCP servers that already exist in Claude Code's config into the ccmcp registry.

ccmcp import

# Overwrite existing registry entries
ccmcp import --overwrite

Existing Claude Code config is left unchanged; only the registry is updated.

---

Registry files

File	Purpose
~/.ccmcp/config.json	Registry — source of truth for all managed servers
~/.ccmcp/state.json	Tracks which locations ccmcp last wrote to, for safe reconciliation

The CCMCP_HOME environment variable overrides ~/.ccmcp (useful for testing).

Two environment variables control which .claude.json file ccmcp reads and writes:

Variable	Behaviour
CCMCP_CLAUDE_CONFIG	Full path to the .claude.json file — takes precedence over everything else
CLAUDE_CONFIG_DIR	Directory that contains .claude.json; ccmcp appends /.claude.json to this path

If neither is set, ccmcp defaults to ~/.claude.json.

Scopes

ccmcp stores two scopes internally:

• global — server is written to Claude Code's user-level config (~/.claude.json), available in all projects.
• project — server is written into a specific project's config section, available only in that project. Defaults to the current working directory.

The --scope flag on add, add-json, and update also accepts Claude Code's own scope names so you can copy commands verbatim: user maps to global, while local and project both map to project.

Development

npm install
npm run build      # compile TypeScript
npm test           # run tests
npm run bundle     # bundle for packaging
npm run package    # build standalone binaries