npm-mcp

npm-mcp es un servidor pequeño y de solo lectura del Model Context Protocol para el registro público de npm. Permite que los clientes de IA compatibles con MCP descubran paquetes npm e inspeccionen metadatos específicos de paquetes sin exponer capacidades de instalación, publicación, inicio de sesión, shell, sistema de archivos o fetch arbitrario.

Comenzar con Docker

Consulta la guía de inicio rápido con Docker para lanzar el servidor y MCP Inspector desde una copia recién clonada. El comando esencial es:

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

Para probar el uso de herramientas MCP impulsado por modelos sin ejecutar un modelo localmente, usa LibreChat con el enrutador de modelos gratuitos de OpenRouter:

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

A continuación, abre http://127.0.0.1:3080. Se requiere una clave API de OpenRouter incluso para los modelos gratuitos. Consulta OPENROUTER_QUICKSTART.md para la configuración y el uso. El perfil local de Ollama sigue disponible como alternativa opcional totalmente local.

Related MCP server: @kongyo2/npm-info-mcp-server

Herramientas

Todas las herramientas devuelven JSON como texto para una amplia compatibilidad con los clientes y exponen el mismo valor como contenido estructurado de MCP. Las respuestas de los paquetes se filtran deliberadamente en lugar de devolver el documento completo de metadatos del registro.

Requisitos e instalación

• Node.js 20 o superior (para fetch nativo y AbortSignal.timeout)

• npm

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

Ejecutar localmente

npm start

El proceso espera mensajes MCP en stdin y escribe respuestas del protocolo en stdout. No escribas interactivamente en él; debe lanzarlo un cliente MCP. El modo de observación de desarrollo está disponible con npm run dev.

Despliegue

Para clientes locales, usa el punto de entrada stdio. Para Docker y despliegues en la nube, usa el punto de entrada HTTP Streamable sin estado en /mcp; requiere un token de portador por defecto y expone /healthz para las comprobaciones de salud. Consulta la guía de despliegue con Docker y en la nube para Docker Compose y las instrucciones de despliegue para Google Cloud Run, Azure Container Apps, AWS App Runner/ECS Fargate y Kubernetes.

El archivo Compose también incluye el MCP Inspector oficial como cliente opcional. Ejecuta docker compose --profile inspector up --build -d y luego abre http://127.0.0.1:6274. Consulta Ejecutar un cliente MCP en Docker para la configuración del token y el uso de la CLI.

Pruebas

npm test

Las pruebas usan el ejecutor de pruebas integrado de Node y respuestas fetch simuladas, por lo que no requieren el registro npm en vivo.

Para inspeccionar el servidor interactivamente con MCP Inspector:

npx @modelcontextprotocol/inspector node src/index.js

Abre la URL que imprime Inspector, conéctate, selecciona Herramientas, elige una herramienta, introduce sus argumentos y ejecútala.

Configuración del cliente MCP

Usa una ruta absoluta para que el cliente pueda iniciar el servidor desde cualquier directorio de trabajo:

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

La clave de configuración externa exacta puede variar según el cliente MCP, pero el comando y los argumentos son los mismos.

Ejemplos de llamadas

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

Arquitectura

• src/index.js solo gestiona el inicio en stdio.

• src/http.js y src/http-server.js proporcionan el punto de entrada HTTP Streamable autenticado que usan los contenedores.

• src/server.js crea el servidor MCP y registra las cuatro herramientas.

• src/tools/ contiene esquemas, conformación específica de respuestas y manejadores.

• src/services/npm-registry.js es el único módulo que se comunica con npm. Valida los nombres de los paquetes, restringe las URL a los endpoints oficiales del registro, aplica un tiempo de espera y normaliza los errores de red/HTTP/respuesta.

Los nombres con ámbito se codifican como un único segmento de ruta del registro. El servidor no tiene estado y no realiza escrituras.

Mejoras futuras

Las posibles incorporaciones posteriores incluyen estadísticas de descargas, análisis de dependencias, información de seguridad de los paquetes, almacenamiento en caché y autenticación remota basada en OAuth.