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

Install

git clone https://github.com/yuchen814/npm-registry-mcp-server.git
cd npm-registry-mcp-server
npm install
npm run build

Configuration

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 --noEmit

Inspect it interactively

npx @modelcontextprotocol/inspector npx tsx ./server.ts

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

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.

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 exist

• VersionNotFoundError — no version satisfies the request (possibly because omitDeprecated filtered 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:

1. node --import ./dist/instrument.js (used by npm start) — preferred, lets the SDK instrument Node internals

2. as the first import in server.ts — so tsx server.ts is instrumented too

instrument.ts guards against double initialization.

License

MIT