⚠️ 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.
| 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 |
npm install -g @verdaccio/mcp-server
# or run without installing
npx @verdaccio/mcp-serverThe 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-serverAdd 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?"
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"
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 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 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"
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 the profile of the currently authenticated user (requires VERDACCIO_TOKEN).
Uses endpoint: PROFILE_API_ENDPOINTS.get_profile → /-/npm/v1/user
List all API tokens for the authenticated user.
Uses endpoint: TOKEN_API_ENDPOINTS.get_tokens → /-/npm/v1/tokens
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 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
npm install
npm run build| Variable | Default | Description |
|---|---|---|
VERDACCIO_URL |
http://localhost:4873 |
Base URL of your Verdaccio instance |
VERDACCIO_TOKEN |
— | Bearer token for authenticated registries |
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"
}
}
}
}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.
# 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@modelcontextprotocol/sdk— MCP server framework@verdaccio/middleware— Verdaccio API endpoint constantszod— Tool input schema validation