@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

Related MCP server: @lpm-registry/mcp-server

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.

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.

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.

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.

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.

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.

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.

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

delete_token

Delete an API token by its key.

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

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