npm-registry-mcp-server
Provides tools for querying the npm registry, including fetching package metadata and listing published versions and dist-tags.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@npm-registry-mcp-server What are the latest versions of express?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
npm-registry-mcp-server
MCP server for npm registry package metadata lookups, powered by
package-json
A production-ready Model Context Protocol server that lets MCP clients (Claude Desktop, Claude Code, MCP Inspector, …) query the npm registry.
Registry access is delegated entirely to package-json@10.0.1, so behaviour matches npm itself:
.npmrc resolution, scoped packages, private registries, bearer/basic auth, dist-tags, and full
semver range resolution all work out of the box.
Transport: stdio (JSON-RPC over stdin/stdout)
Validation: zod on every tool input
Monitoring: Sentry initialized before the server starts
Requirements
Node.js >= 18.19.0.
package-json, @sentry/node, and @modelcontextprotocol/sdk all declare node: >=18. This
project raises the floor to 18.19.0 because ESM preloading via node --import — how Sentry is
loaded ahead of everything else — was added in 18.19.0.
Related MCP server: MCP Server for NPM Package Info
Install
git clone https://github.com/yuchen814/npm-registry-mcp-server.git
cd npm-registry-mcp-server
npm install
npm run buildConfiguration
Variable | Required | Description |
| No | Sentry DSN. When unset, Sentry is initialized in a disabled state and the server runs normally. |
| No | Falls back to |
| No | Release identifier for grouping issues. |
| No |
|
Copy .env.example as a starting point. The DSN is only ever read from the environment — it is
never hardcoded.
Registry URL and credentials are not configured here. package-json reads them from your
.npmrc exactly like npm does, which is what makes private and scoped packages work.
Usage
npm start # builds, then: node --import ./dist/instrument.js ./dist/server.js
npm run dev # tsx server.ts (no build step)
npm run typecheck # tsc --noEmitInspect it interactively
npx @modelcontextprotocol/inspector npx tsx ./server.tsRegister with an MCP client
{
"mcpServers": {
"npm-registry": {
"command": "node",
"args": [
"--import",
"/absolute/path/to/npm-registry-mcp-server/dist/instrument.js",
"/absolute/path/to/npm-registry-mcp-server/dist/server.js"
],
"env": {
"SENTRY_DSN": "https://examplePublicKey@o0.ingest.sentry.io/0"
}
}
}
}Tools
get_npm_package_metadata
Fetch metadata for a package. Arguments mirror the package-json API one-to-one.
Argument | Type | Default | Description |
|
| — | Required. npm package name. Scoped names supported ( |
|
|
| Exact version, dist-tag, or semver range: |
|
|
| Return the full metadata document rather than the abbreviated one. |
|
|
| Return the registry's main entry containing all versions. Takes precedence over |
|
| auto-detected | Registry override. Intended for internal tooling only — prefer |
|
|
| Omit deprecated versions. An explicit version or dist-tag is still returned even if deprecated. |
Structured output: packageName, requestedVersion, resolvedVersion, fullMetadata,
allVersions, omitDeprecated, registryUrl, and the raw metadata document.
// { "packageName": "package-json", "version": "10.0.1" }
// -> resolvedVersion: "10.0.1", metadata: { name, version, dependencies, dist, ... }list_npm_package_versions
List published versions and dist-tags, newest first.
Argument | Type | Default | Description |
|
| — | Required. npm package name. |
|
|
| Max versions to return (1–1000). |
|
| auto-detected | Registry override. |
Structured output: packageName, totalVersions, versions, distTags, latest, truncated.
Error handling
The two error classes from package-json are treated as expected outcomes, not defects:
PackageNotFoundError— the package name does not existVersionNotFoundError— no version satisfies the request (possibly becauseomitDeprecatedfiltered it out)
Both are returned to the client as tool errors and recorded as Sentry breadcrumbs only. Everything else — DNS/network failures, registry 5xx, auth problems, bugs — is captured to Sentry with the tool name, package name, and a local-variable-enriched stack trace, then returned as a tool error. The server never crashes on a failed lookup.
Notes for contributors
stdout is the MCP protocol channel. Never console.log from this server — all diagnostics go to
stderr, and Sentry's debug option is pinned to false for the same reason.
Sentry is loaded two ways so it is always initialized before the server:
node --import ./dist/instrument.js(used bynpm start) — preferred, lets the SDK instrument Node internalsas the first
importinserver.ts— sotsx server.tsis instrumented too
instrument.ts guards against double initialization.
License
MIT
Available Tools
2 toolsget_npm_package_metadataGet npm package metadataARead-onlyIdempotent
Fetch metadata for a package from the npm registry. Requires a package name and optionally accepts a version, dist-tag, or semver range (defaults to "latest"). By default an abbreviated metadata document is returned for performance; set fullMetadata to true for the complete document. Set allVersions to true to get the registry's main entry containing every version (this takes precedence over version). Works with scoped and private packages, honouring .npmrc registry and auth settings.
Inputs: packageName (required), version, allVersions, registryUrl, +2 more. Returns: metadata, allVersions, packageName, registryUrl, +4 more
list_npm_package_versionsList npm package versionsARead-onlyIdempotent
List published version numbers and dist-tags for a package from the npm registry, newest first. Useful for checking what versions exist before requesting metadata for a specific one.
Inputs: packageName (required), limit, registryUrl. Returns: latest, distTags, versions, truncated, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct primary purposes: fetching metadata for a package (or specific version) versus listing available versions and dist-tags. While get_npm_package_metadata with allVersions can also return version information, the descriptions make the intended use of each tool unambiguous.
Both tool names follow a consistent verb_noun pattern with snake_case: get_npm_package_metadata and list_npm_package_versions. The verbs 'get' and 'list' are appropriate for their respective operations, and the naming is predictable and uniform.
With only 2 tools, the server feels slightly thin for an npm registry surface, as it could reasonably include operations like search or package file downloads. However, the narrow read-only metadata focus makes this count defensible and not excessive.
The server covers the core read-only operations for npm package metadata: retrieving metadata (with version, tag, or range options) and listing available versions. Minor gaps exist, such as no direct search or readme retrieval, but these are not essential for the stated purpose of querying package information.
Maintenance
Related MCP Connectors
Dive into the world of npm with our NPM Package Info MCP. Access crucial metadata about any npm
Unofficial npm MCP — wraps the npm Registry API (free, no auth)
Market data tools for the MCP ecosystem: server stats, events, search, leaderboards, package trends.
Unofficial PyPI MCP — wraps the Python Package Index (PyPI) JSON API (free, no auth).
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server to search npm packages, view details, compare, check downloads, and inspect dependencies.645 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides a tool to fetch npm package information via the Model Context Protocol.8Apache 2.0
- AlicenseAqualityCmaintenanceFetches npm package READMEs, metadata, and search results for MCP-compatible AI clients.310 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides a tool to fetch npm package information via MCP. Enables AI agents to retrieve structured package details using the getNpmPackageInfo tool.Apache 2.0