@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: npm-mcp

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. 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"

login

Authenticate with username and password. Returns a Bearer token.

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

npm install
npm run 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 npm run 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 npm run dev

# Build and run compiled output
npm run build
npm start

# Run tests
npm test
npm run test:watch

Stack

• @modelcontextprotocol/sdk — MCP server framework

• @verdaccio/middleware — Verdaccio API endpoint constants

• zod — Tool input schema validation