npm-mcp

npm-mcp 是一个小型的、只读的 Model Context Protocol 服务器，用于公共 npm 注册表。它让兼容 MCP 的 AI 客户端能够发现 npm 包并检查重点包元数据，而不会暴露安装、发布、登录、shell、文件系统或任意抓取（fetch）能力。

通过 Docker 启动

请参阅 Docker 快速入门，从全新的检出（checkout）启动服务器和 MCP Inspector。基本命令如下：

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

若要在不本地运行模型的情况下测试模型驱动的 MCP 工具使用，请使用 LibreChat 与 OpenRouter 的免费模型路由器：

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

然后打开 http://127.0.0.1:3080。即使是免费模型也需要 OpenRouter API 密钥。有关设置和使用，请参阅 OPENROUTER_QUICKSTART.md。本地 Ollama 配置文件 仍可作为可选的完全本地替代方案。

Related MCP server: npm-mcp

工具

所有工具均以 JSON 文本形式返回，以实现广泛的客户端兼容性，并将相同值作为 MCP 结构化内容公开。包响应经过刻意过滤，而不是返回注册表的完整元数据文档。

要求与安装

• Node.js 20 或更高版本（用于原生 fetch 和 AbortSignal.timeout）

• npm

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

本地运行

npm start

该进程在 stdin 上等待 MCP 消息，并将协议响应写入 stdout。请勿在其中进行交互式输入；应由 MCP 客户端启动它。开发监听模式可通过 npm run dev 使用。

部署

对于本地客户端，请使用 stdio 入口点。对于 Docker 和云部署，请使用位于 /mcp 的无状态 Streamable HTTP 入口点；它默认需要 bearer token，并公开 /healthz 用于健康检查。有关 Docker Compose 以及 Google Cloud Run、Azure Container Apps、AWS App Runner/ECS Fargate 和 Kubernetes 的部署说明，请参阅 Docker 和云部署指南。

Compose 文件还包含官方 MCP Inspector 作为可选客户端。运行 docker compose --profile inspector up --build -d，然后打开 http://127.0.0.1:6274。有关 token 设置和 CLI 用法，请参阅 在 Docker 中运行 MCP 客户端。

测试

npm test

测试使用 Node 内置的测试运行器和模拟的 fetch 响应，因此不需要实时的 npm 注册表。

要与 MCP Inspector 交互式地检查服务器：

npx @modelcontextprotocol/inspector node src/index.js

打开 Inspector 打印的 URL，连接，选择 Tools，选择工具，输入其参数，然后运行它。

MCP 客户端配置

使用绝对路径，以便客户端可以从任何工作目录启动服务器：

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

确切的外部配置键可能因 MCP 客户端而异，但命令和参数是相同的。

示例调用

{"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"}}

架构

• src/index.js 仅负责 stdio 启动。

• src/http.js 和 src/http-server.js 提供容器使用的经过身份验证的 Streamable HTTP 入口点。

• src/server.js 创建 MCP 服务器并注册这四个工具。

• src/tools/ 包含模式、聚焦的响应整形和处理程序。

• src/services/npm-registry.js 是唯一与 npm 通信的模块。它验证包名，将 URL 限制为官方注册表端点，应用超时，并规范化网络/HTTP/响应错误。

作用域名称被编码为单个注册表路径段。该服务器是无状态的，并且不执行任何写入操作。

未来改进

未来可能添加的内容包括下载统计、依赖分析、包安全信息、缓存以及基于 OAuth 的远程身份验证。