npmswitch

An MCP server and CLI for the npm registry that manages multiple accounts (personal, org, scoped) and routes each call to the right token. It speaks plain MCP over stdio, so it works with any MCP-capable agent: Claude Code and Desktop, Cursor, GitHub Copilot (VS Code), Windsurf, Cline, Gemini CLI, Codex CLI, opencode, Continue, Hermes Agent, Zed and others.

Sibling of Octoswitch, the same idea for GitHub accounts. Not affiliated with or endorsed by npm, Inc. or GitHub.

Why

The npm CLI keeps one login at a time. This keeps several named accounts and picks one per call:

1. an explicit account argument (name or npm username), else

2. the account whose username or --scopes match the package scope (@acme/tool uses the account that owns @acme), else

3. the default account.

Related MCP server: pkg-booper

Setup

git clone https://github.com/ApiCartOps/npmswitch.git
cd npmswitch
npm install
npm link                      # puts the `npmswitch` command on your PATH

npmswitch add personal --default
npmswitch add work --scopes=@acme,@tools
npmswitch list

  NAME      LOGIN  SCOPES
* personal  alice
  work      bob    @acme @tools

Without npm link, run node src/cli.js in place of npmswitch. From npm, npm install -g @apicartops/npmswitch installs the same npmswitch command (the package is scoped because npm rejects npmswitch as too similar to an existing package).

add asks for the token at a hidden prompt (or reads it from an env var with --token-env=VAR), checks it against the registry and stores the username. Tokens are never passed on the command line, never printed, and never returned by any tool. They are stored in ~/.npmswitch/accounts.json (file mode 600).

Tokens. Create one per account at npmjs.com under Access Tokens. A read-only token is enough for lookups. For deprecate, dist-tags and publish, use a granular token with read and write on the packages, or an automation token. Accounts that require a one-time code work too: pass it as otp.

Connect it to your agent

npmswitch agents                 # what is supported, and what looks installed
npmswitch install cursor         # or: claude-code, vscode, codex, gemini-cli, ... or: all
npmswitch install cursor --dry-run
npmswitch config hermes          # print the snippet instead of editing anything

install merges one entry into the agent's user-level MCP config and leaves everything else in the file alone. It refuses to touch a file it cannot parse (for example JSON with comments) and prints the snippet instead. uninstall <agent> removes it. Restart the agent afterwards.

Config locations differ between versions of these tools, so check the printed path if an agent does not pick it up. Use --npx to register npx -y @apicartops/npmswitch mcp instead of a path to this checkout (once published), and --name=NAME to use a different server name.

Project instructions

npmswitch init              # AGENTS.md, plus any of CLAUDE.md / GEMINI.md / copilot / cursor rule that already exist
npmswitch init --all        # write all five

This adds a short, marked block telling the agent to use the npm_* tools and to confirm before any write. Re-running updates the block in place.

What it exposes

Tools (all agents):

Publishing is safe by default. npm_publish is a dry run unless dry_run: false is passed, and its description tells agents to show you the account, name, version and file list and to wait for a yes before publishing for real. A published version can never be reused. The token reaches npm through a temporary config file (mode 600) that is deleted afterwards, never on the command line, and is scrubbed from the output. Packages marked "private": true are refused. The package's own lifecycle scripts run, as with npm publish; set ignore_scripts to skip them.

Server instructions: the same guidance is sent in the MCP initialize response, so clients that surface it need no extra setup.

Prompts (commands, for clients that support MCP prompts): npm_accounts, npm_package_health, npm_release_check, npm_deprecate. They take one optional argument such as a package name or a directory.

Resource: npmswitch://accounts (names, usernames and scopes only).

Claude Code extras (installed by install claude-code): the npmswitch skill in ~/.claude/skills/ and the slash commands /npm-accounts, /npm-package-health, /npm-release-check and /npm-deprecate in ~/.claude/commands/. The sources live in content/, including a standard SKILL.md you can copy into any agent that supports Agent Skills.

CLI reference

Test

npm test

Runs against a fake registry with temporary config and home folders, including a real npm publish to the fake registry; no real accounts or agent configs are touched.

License

MIT