npm-mcp

npm-mcp is a small, read-only Model Context Protocol server for the public npm registry. It lets MCP-compatible AI clients discover npm packages and inspect focused package metadata without exposing install, publish, login, shell, filesystem, or arbitrary-fetch capabilities.

Start with Docker

See the Docker quick start to launch the server and MCP Inspector from a fresh checkout. The essential command is:

docker compose --profile inspector up --build -d

To test model-driven MCP tool use without running a model locally, use LibreChat with OpenRouter's free-model router:

docker compose -f compose.yaml -f compose.openrouter.yaml --profile openrouter up --build -d

Then open http://127.0.0.1:3080. An OpenRouter API key is required even for free models. See OPENROUTER_QUICKSTART.md for setup and usage. The local Ollama profile remains available as an optional fully local alternative.

Tools

Tool	Use it when	Input
npm_search_packages	The exact package name is unknown or alternatives are wanted	query, optional limit (default 10, max 50)
npm_get_package	The exact package name is known and metadata or dependencies are needed	packageName
npm_get_latest_version	Only the current latest dist-tag is needed	packageName
npm_get_versions	Published versions and all dist-tags are needed	packageName

All tools return JSON as text for broad client compatibility and expose the same value as MCP structured content. Package responses are deliberately filtered rather than returning the registry's full metadata document.

Requirements and installation

• Node.js 20 or newer (for native fetch and AbortSignal.timeout)
• npm

git clone <repository-url>
cd npm-mcp
npm install

Run locally

npm start

The process waits for MCP messages on stdin and writes protocol responses to stdout. Do not type interactively into it; an MCP client should launch it. Development watch mode is available with npm run dev.

Deployment

For local clients, use the stdio entry point. For Docker and cloud deployment, use the stateless Streamable HTTP entry point at /mcp; it requires a bearer token by default and exposes /healthz for health probes. See the Docker and cloud deployment guide for Docker Compose and deployment instructions for Google Cloud Run, Azure Container Apps, AWS App Runner/ECS Fargate, and Kubernetes.

The Compose file also includes the official MCP Inspector as an optional client. Run docker compose --profile inspector up --build -d, then open http://127.0.0.1:6274. See Run an MCP client in Docker for token setup and CLI usage.

Test

npm test

Tests use Node's built-in test runner and mocked fetch responses, so they do not require the live npm registry.

To inspect the server interactively with MCP Inspector:

npx @modelcontextprotocol/inspector node src/index.js

Open the URL printed by Inspector, connect, select Tools, choose a tool, enter its arguments, and run it.

MCP client configuration

Use an absolute path so the client can start the server from any working directory:

{
  "mcpServers": {
    "npm": {
      "command": "node",
      "args": ["/absolute/path/to/npm-mcp/src/index.js"]
    }
  }
}

The exact outer configuration key can vary by MCP client, but the command and arguments are the same.

Example calls

{"name":"npm_search_packages","arguments":{"query":"postgres orm","limit":10}}

{"name":"npm_get_package","arguments":{"packageName":"@nestjs/core"}}

{"name":"npm_get_latest_version","arguments":{"packageName":"react"}}

{"name":"npm_get_versions","arguments":{"packageName":"axios"}}

Architecture

• src/index.js owns stdio startup only.
• src/http.js and src/http-server.js provide the authenticated Streamable HTTP entry point used by containers.
• src/server.js creates the MCP server and registers the four tools.
• src/tools/ contains schemas, focused response shaping, and handlers.
• src/services/npm-registry.js is the only module that communicates with npm. It validates package names, constrains URLs to the official registry endpoints, applies a timeout, and normalizes network/HTTP/response errors.

Scoped names are encoded as a single registry path segment. The server is stateless and performs no writes.

Future improvements

Possible later additions include download statistics, dependency analysis, package security information, caching, and OAuth-based remote authentication.