mcpsmgr

Unified MCP (Model Context Protocol) server manager for multiple AI coding agents — define MCP servers once, sync them to Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Antigravity, OpenClaw, and Hermes Agent from one place.

中文文档

Quick Start

# Install one or many MCP servers from a GitHub repo
npx mcpsmgr add jtianling/cross-agent-teams-mcp -a claude-code -y

# Or interactively pick which agent to deploy to
npx mcpsmgr add anthropics/some-mcp-server

That's it. mcpsmgr fetches the repo's mcpsmgr.json manifest (or falls back to README scanning), records the server in your central repository at ~/.mcps-manager/servers/, and writes the right config into your agent's native file (.claude.json, .codex/config.toml, etc.).

Need to deploy already-installed servers into a fresh project? cd into the project and run npx mcpsmgr deploy.

Install

npm install -g mcpsmgr     # or pnpm add -g / yarn global add

Or run anywhere without installing:

npx mcpsmgr <command>

Adding servers to a project (add)

mcpsmgr add is the main entry point. It accepts three input shapes:

mcpsmgr add my-server                                  # already in central repo
mcpsmgr add owner/repo                                 # GitHub shorthand
mcpsmgr add https://github.com/owner/repo              # full GitHub URL
mcpsmgr add repo                                       # repo basename (bundle reverse-lookup)

The resolver picks the matching central entry or bundle when one exists, and falls back to fetching the manifest only when nothing is cached locally. This means re-running add owner/repo after the first install is fast and offline-safe.

Useful flags

-a, --agent <id>     Target a specific agent without prompting
-y                   Unattended: auto-select detected agents, overwrite existing,
                     fail-fast on missing required vars/env (implies --force)
-f, --force          Overwrite existing central entries without confirmation
--port <number>      Override manifest variables.port (manifest-driven flow)
--global             Write agent config to the agent's global config location
                     instead of the project (codex: ~/.codex/config.toml,
                     opencode: ~/.config/opencode/opencode.json,
                     kimi-code: ~/.kimi-code/mcp.json)
--var <name=value>   Provide manifest env var / variable values non-interactively
                     (repeatable, manifest-driven flow)

-y is the CI-friendly switch: one flag, no prompts. It will refuse rather than silently substitute defaults when a required variable or env var is missing — set those explicitly before re-running.

Manifest env var values resolve in priority order --var > process environment > interactive prompt, so an exported token (or an explicit --var NAME=VALUE) makes add fully non-interactive even without -y.

Codex-specific behavior: HTTP servers get a top-level experimental_use_rmcp_client = true compatibility switch (older Codex requires it to load streamable-http MCP servers; newer versions default to rmcp and tolerate the key), and a manifest env var applied as an Authorization: Bearer header is written as bearer_token_env_var = "<NAME>" instead of a plaintext header — the token stays in the environment, never in the config file. Use --global when Codex runs with --remote/app-server, which loads MCP servers from ~/.codex/config.toml (CODEX_HOME) rather than the project-level file.

Kimi Code-specific behavior: entries are written in Kimi's native shape — an explicit transport discriminator, a native env table for stdio, and bearerTokenEnvVar instead of a plaintext Authorization header for HTTP. Kimi loads three MCP files (~/.kimi-code/mcp.json, the project-root .mcp.json it shares with Claude Code, and the project-local .kimi-code/mcp.json) and merges them per server key, with later files winning. Two consequences: remove on the project-local file does not uninstall a server that the shared root .mcp.json also declares, and hiding such a server needs enabled: false rather than omission (see below).

A manifest server config, or a per-agent override, may carry enabled: false to write an entry that the agent loads but keeps switched off. This is what masks a server inherited from an earlier config layer — the case it exists for is a stdio side-channel that only Claude Code understands and that would otherwise fail on startup under Kimi. Agents with no equivalent concept ignore the field and never write it.

Installing servers into the central repository (install)

add writes to the central repository as a side effect when it pulls a remote manifest. If you only want to register a server without touching any project, use install:

mcpsmgr install owner/repo                  # GitHub source (manifest or README scan)
mcpsmgr install https://github.com/o/r
mcpsmgr install ./my-mcp.json               # any agent's MCP JSON shape
mcpsmgr install ~/workspace/my-mcp-server   # local project directory
mcpsmgr install                             # interactive manual flow

GitHub sources also update ~/.mcps-manager/bundles.json so later add repo calls can resolve back to every server the repo declared.

Deploying to agents (deploy)

cd your-project
mcpsmgr deploy             # pick which central servers to deploy
mcpsmgr deploy --refresh   # re-sync existing project entries from central

deploy autodetects which agents the project already uses (presence of .claude.json, .codex/, etc.) and only writes to those. --refresh is the right command after you tweak a server definition in the central repository and want every project to pick up the change.

Inspecting and removing

mcpsmgr list                  # central repository
mcpsmgr list --deployed       # what's wired up in the current project
mcpsmgr remove <name>         # remove from the current project (per-agent prompt)
mcpsmgr uninstall <name>      # remove from the central repository
mcpsmgr update [name]         # re-analyze sources and patch central definitions

remove only touches project agent configs. uninstall removes the central entry (and prunes it from any bundle it belongs to).

Supported agents

Gotcha — global agents. Antigravity, OpenClaw, and Hermes Agent share a single config across every project on the machine. add and deploy leave them unchecked by default; tick them only if you really want a host-wide change.

Agent ids for -a flag. claude-code, codex, cursor, gemini-cli, opencode, antigravity, openclaw, hermes-agent, kimi-code.

GitHub bundles (reverse-lookup)

When a single GitHub repo declares multiple MCP servers via mcpsmgr.json, mcpsmgr records them as one bundle. After the first install, any of these inputs resolve to the same set of servers without going back to the network:

mcpsmgr add jtianling/cross-agent-teams-mcp        # owner/repo
mcpsmgr add https://github.com/jtianling/cross-agent-teams-mcp
mcpsmgr add cross-agent-teams-mcp                  # bare repo name

Bundles are stored in ~/.mcps-manager/bundles.json. install updates the bundle membership on every successful manifest install; uninstall <name> prunes the member and drops the bundle when it becomes empty.

Gotcha — repo-name collisions. If two different GitHub owners publish repos with the same basename and you've installed both, mcpsmgr add <basename> will refuse with a list of candidates. Disambiguate with owner/repo.

License

MIT