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

login

Authenticate with username and password. Returns a Bearer token.

| 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

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