@verdaccio/mcp-server

⚠️ Experimental: This project is a work in progress and subject to change. APIs, tool names, and behaviour may change without notice between versions.

An MCP (Model Context Protocol) server that connects any MCP-compatible AI client to a Verdaccio private npm registry.

MCP is an open protocol — this server works with any MCP client, not just Claude.

API endpoint paths are sourced directly from @verdaccio/middleware constants (e.g. SEARCH_API_ENDPOINTS, PACKAGE_API_ENDPOINTS) so they stay in sync with Verdaccio's own routing definitions.

Compatible clients

Client	Config location
Claude Desktop / Claude Code	`~/.claude.json` or workspace `.mcp.json`
Cursor	`.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
VS Code + Copilot	`.vscode/mcp.json`
Continue.dev	`~/.continue/config.json`
Any custom app	MCP SDK

Installation

npm install -g @verdaccio/mcp-server

# or run without installing
npx @verdaccio/mcp-server

Using with Claude

Claude Code (CLI)

The quickest way is via the claude mcp add command:

# Local scope (current project only)
claude mcp add verdaccio -e VERDACCIO_URL=http://your-verdaccio:4873 -- npx @verdaccio/mcp-server

# User scope (all projects)
claude mcp add -s user verdaccio -e VERDACCIO_URL=http://your-verdaccio:4873 -- npx @verdaccio/mcp-server

# With auth token
claude mcp add verdaccio \
  -e VERDACCIO_URL=http://your-verdaccio:4873 \
  -e VERDACCIO_TOKEN=your-token \
  -- npx @verdaccio/mcp-server

Claude Desktop

Add to ~/.claude.json:

{
  "mcpServers": {
    "verdaccio": {
      "command": "npx",
      "args": ["@verdaccio/mcp-server"],
      "env": {
        "VERDACCIO_URL": "http://your-verdaccio:4873",
        "VERDACCIO_TOKEN": "your-token"
      }
    }
  }
}

Restart Claude after adding the config. You can verify the server is connected by asking:

"What tools do you have available for Verdaccio?"

Tools

`start_registry`

Start the Verdaccio registry and return its URL. When no VERDACCIO_URL is configured, an embedded registry is started automatically on a random local port with temporary storage.

No parameters required.

Example prompt: "Start a local Verdaccio registry so I can publish packages"

`find_package`

Search for packages in the registry by name or keyword.

Parameter	Type	Required	Description
`query`	string	yes	Package name or search term
`size`	number	no	Max results to return (1–100, default 20)

Uses endpoint: SEARCH_API_ENDPOINTS.search → /-/v1/search

Example prompt: "Find all packages related to authentication in our private registry"

`get_package`

Get detailed metadata for a specific package — description, author, license, dist-tags, and version history.

Parameter	Type	Required	Description
`package`	string	yes	Package name, e.g. `my-lib` or `@scope/my-lib`
`version`	string	no	Specific version e.g. `1.2.3` (omit for latest)

Uses endpoint: PACKAGE_API_ENDPOINTS.get_package_by_version → /:package{/:version}

Example prompt: "What versions of @myorg/ui-components are available?"

`publish_package`

Publish a package to the registry by name and version. Checks whether the package already exists and prevents re-publishing an existing version. Uses generatePackageMetadata from @verdaccio/test-helper to generate the full publish payload automatically — no tarball needed.

Parameter	Type	Required	Description
`name`	string	yes	Package name, e.g. `my-lib` or `@scope/my-lib`
`version`	string	yes	Version to publish, e.g. `1.0.0`
`tag`	string	no	Dist-tag to apply (default: `latest`)

Uses endpoint: PUBLISH_API_ENDPOINTS.add_package → /:package

Example prompt: "Publish @myorg/ui-components version 2.1.0 to our private registry"

`unpublish_package`

Unpublish a specific version of a package from the registry. Fetches the current metadata, removes the target version, drops dist-tags that pointed at it (moving latest to the highest remaining stable version), and deletes the tarball. Unpublishing the last version removes the whole package. This is a 3-step operation (GET → PUT → DELETE) — if the final step fails, metadata may already be updated.

Parameter	Type	Required	Description
`name`	string	yes	Package name, e.g. `my-lib` or `@scope/my-lib`
`version`	string	yes	Version to unpublish, e.g. `1.0.3`

Example prompt: "Unpublish version 1.0.3 of @myorg/ui-components from the registry"

`add_user`

Register a new user in the Verdaccio registry. Returns a Bearer token on success.

Parameter	Type	Required	Description
`username`	string	yes	Desired username
`password`	string	yes	Desired password

Uses endpoint: USER_API_ENDPOINTS.add_user → /-/user/:org_couchdb_user

Example prompt: "Register a new user called jdoe in Verdaccio"

`login`

Authenticate with username and password using Basic auth, so Verdaccio's authenticate branch issues a token. As with npm login, if the user does not exist and registration is open, Verdaccio creates it; the tool reports when that happens.

Parameter	Type	Required	Description
`username`	string	yes	Verdaccio username
`password`	string	yes	Verdaccio password

Uses endpoint: USER_API_ENDPOINTS.add_user → /-/user/:org_couchdb_user

`get_profile`

Get the profile of the currently authenticated user (requires VERDACCIO_TOKEN).

Uses endpoint: PROFILE_API_ENDPOINTS.get_profile → /-/npm/v1/user

`list_tokens`

List all API tokens for the authenticated user.

Uses endpoint: TOKEN_API_ENDPOINTS.get_tokens → /-/npm/v1/tokens

`create_token`

Create a new API token for the authenticated user.

Parameter	Type	Required	Description
`password`	string	yes	Current user password
`readonly`	boolean	no	Make token read-only (default false)
`cidr`	string[]	no	IP ranges to whitelist, e.g. `["10.0.0.0/8"]`

Uses endpoint: TOKEN_API_ENDPOINTS.get_tokens → /-/npm/v1/tokens (POST)

`delete_token`

Delete an API token by its key.

Parameter	Type	Required	Description
`tokenKey`	string	yes	Token key identifier (from `list_tokens`)

Uses endpoint: TOKEN_API_ENDPOINTS.delete_token → /-/npm/v1/tokens/token/:tokenKey

Example

Setup

1. Install and build

pnpm install
pnpm build

2. Configure environment

Variable	Default	Description
`VERDACCIO_URL`	`http://localhost:4873`	Base URL of your Verdaccio instance
`VERDACCIO_TOKEN`	—	Bearer token for authenticated registries

3. Add to your MCP client

The server config format is the same across all clients — only the config file location differs (see Compatible clients above).

{
  "mcpServers": {
    "verdaccio": {
      "command": "npx",
      "args": ["@verdaccio/mcp-server"],
      "env": {
        "VERDACCIO_URL": "http://your-verdaccio:4873",
        "VERDACCIO_TOKEN": "your-token"
      }
    }
  }
}

Development

Testing locally without publishing

To connect your MCP client to the local source without publishing to npm, point it directly at the local file.

Option A — compiled (requires pnpm build after each change):

{
  "mcpServers": {
    "verdaccio": {
      "command": "node",
      "args": ["/path/to/mcp-server-verdaccio/dist/index.js"],
      "env": {
        "VERDACCIO_URL": "http://localhost:4873"
      }
    }
  }
}

Option B — TypeScript directly via tsx (no build step, recommended for dev):

{
  "mcpServers": {
    "verdaccio": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-server-verdaccio/src/index.ts"],
      "env": {
        "VERDACCIO_URL": "http://localhost:4873"
      }
    }
  }
}

With option B, just save your changes and restart the MCP client — no build step needed.

Running standalone

# Run directly with tsx (no build step)
VERDACCIO_URL=http://localhost:4873 pnpm dev

# Build and run compiled output
pnpm build
pnpm start

# Run tests
pnpm test
pnpm test:watch

Releasing

Add a changeset with pnpm changeset in any PR that should be released. Merging to main opens a "chore: release" PR; merging that PR publishes to npm.

Stack

@modelcontextprotocol/sdk — MCP server framework
@verdaccio/middleware — Verdaccio API endpoint constants
zod — Tool input schema validation

Name		Name	Last commit message	Last commit date
.changeset		.changeset
.github/workflows		.github/workflows
assets		assets
scripts		scripts
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.nvmrc		.nvmrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

@verdaccio/mcp-server

Compatible clients

Installation

Using with Claude

Claude Code (CLI)

Claude Desktop

Tools

`start_registry`

`find_package`

`get_package`

`publish_package`

`unpublish_package`

`add_user`

`login`

`get_profile`

`list_tokens`

`create_token`

`delete_token`

Example

Setup

1. Install and build

2. Configure environment

3. Add to your MCP client

Development

Testing locally without publishing

Running standalone

Releasing

Stack

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

@verdaccio/mcp-server

Compatible clients

Installation

Using with Claude

Claude Code (CLI)

Claude Desktop

Tools

start_registry

find_package

get_package

publish_package

unpublish_package

add_user

login

get_profile

list_tokens

create_token

delete_token

Example

Setup

1. Install and build

2. Configure environment

3. Add to your MCP client

Development

Testing locally without publishing

Running standalone

Releasing

Stack

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`start_registry`

`find_package`

`get_package`

`publish_package`

`unpublish_package`

`add_user`

`login`

`get_profile`

`list_tokens`

`create_token`

`delete_token`