npmlens-mcp
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., "@npmlens-mcp search for react form libraries"
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.
npmlens-mcp lets your coding agent (such as Claude, Cursor, Copilot,
Gemini or Codex) search the npm registry and fetch package context
(README, downloads, GitHub info, usage snippets). It acts as a
Model‑Context‑Protocol (MCP) server, giving your AI assistant a
structured way to discover libraries and integrate them quickly.
Changelog | Contributing | Troubleshooting | Tool reference
Related MCP server: NPM Context Agent MCP
Key features
Structured npm search with optional ranking weights.
Direct README fetch (optionally truncated).
Enriched package info (downloads + GitHub details).
Usage snippet extraction from README.
Stdio MCP transport, ready for MCP‑compatible clients.
Disclaimers
npmlens-mcp performs network requests to npm and GitHub when tools are
used. Avoid sharing secrets in prompts; set GITHUB_TOKEN only if you
want higher GitHub rate limits.
Requirements
Node.js v18.17 or newer
npm (or pnpm)
Getting started
Add the following config to your MCP client:
{
"mcpServers": {
"npmlens": {
"command": "npx",
"args": ["-y", "npmlens-mcp@latest"]
}
}
}Usingnpmlens-mcp@latest ensures your MCP client always runs the
latest published version.
MCP Client configuration
amp mcp add npmlens -- npx npmlens-mcp@latestclaude mcp add npmlens npx npmlens-mcp@latestcodex mcp add npmlens -- npx npmlens-mcp@latestStart Copilot CLI:
copilotStart the dialog to add a new MCP server by running:
/mcp addConfigure the following fields and press CTRL+S to save:
Server name:
npmlensServer Type:
LocalCommand:
npx -y npmlens-mcp@latest
code --add-mcp '{"name":"npmlens","command":"npx","args":["-y","npmlens-mcp@latest"]}'Go to Cursor Settings -> MCP -> New MCP Server. Use the config provided above.
Project wide:
gemini mcp add npmlens npx npmlens-mcp@latestGlobally:
gemini mcp add -s user npmlens npx npmlens-mcp@latestAlternatively, follow the Gemini CLI MCP guide and use the standard config from above.
Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP)
-> Add. Use the config provided above. Same for Junie under
Settings | Tools | Junie | MCP Settings -> Add.
Go to Settings | AI | Manage MCP Servers -> + Add and use the
config provided above.
Your first prompt
Enter one of the following prompts in your MCP client to check if everything works:
Basic search and info:
Find 5 React debounce hook libraries, include weekly downloads, and
fetch the README for the top result.Compare packages:
Compare react-query, swr, and apollo-client. Show me their weekly
downloads, GitHub stars, and licenses.Version history:
Show me all TypeScript versions released in the last 6 months with
their publish dates.Dependencies:
What are the dependencies of express? Include dev dependencies.Advanced and Local Usage
Looking for JSON‑RPC examples, tool schemas, the local dev CLI, troubleshooting, or contributor setup?
See
docs/advanced.mdfor all technical details.See
CONTRIBUTING.mdfor contributing guidelines.
Tools
Below are the tools exposed by NPMLens MCP. For full JSON schemas, see the Tool reference.
Core Search & Information
search_npmSearch the npm registry with optional ranking weights.
Args:
query(string, required),size(1..250),from(offset),weights(object withquality,popularity,maintenance).Returns:
{ total, results[] }where each result includesname,version,description,links,score, etc.
search_by_keywordsSearch npm packages by specific keywords/tags with AND/OR operators.
Args:
keywords(array of strings, required),operator(AND|OR, defaultAND),size(1..250).Returns: Same as
search_npm.Example: Find packages with "react" AND "hooks" AND "typescript".
get_readmeFetch README markdown for a package (optionally by version).
Args:
name(string, required),version(string),truncateAt(number).Returns: JSON metadata (
name,version,repository,homepage) and the README as text content.
get_package_infoEnriched package info combining registry metadata, npm downloads, and GitHub details.
Args:
name(string, required),version(string),includeReadme(boolean).Returns:
name,version,repository,homepage,github{ fullName, url, stars, forks, license },downloadsLastWeek, and optionalreadme.
get_usage_snippetExtract a likely usage snippet from a package README.
Args:
name(string, required),version(string).Returns:
{ snippet: { language, code, heading } }.
Version & Dependency Analysis
get_package_versionsList all available versions of a package with publish dates and dist tags.
Args:
name(string, required),limit(number),since(string - ISO date or relative like "6 months").Returns:
{ name, versions[] }where each version includesversion,date,tags[].Example: "Show me all React versions from the last year".
get_package_dependenciesGet the dependency tree for a package.
Args:
name(string, required),version(string),depth(1-3, default 1),includeDevDependencies(boolean).Returns:
{ name, version, dependencies[], devDependencies[] }with name and version range for each dependency.Example: "What dependencies does express have?".
Metrics & Comparison
get_downloadsFetch npm downloads for the last
day/week/month.Args:
name(string, required),period(day|week|month, defaultweek).Returns:
{ downloads, start, end, package }.
compare_packagesCompare multiple npm packages side-by-side.
Args:
packages(array of 1-10 package names, required).Returns: Array of comparison data with
name,version,description,downloads,stars,forks,license,repository,homepage, and optionalerror.Fetches all packages in parallel for performance.
Example: "Compare react-query, swr, and apollo-client".
Sample usage queries
Below are example queries you can use with your AI assistant to test all 9 NPMLens tools:
search_npm
Search npm for react testing librariesFind packages related to "typescript validation" and show me the top 5 resultsget_readme
Show me the README for expressGet the README for react version 18.0.0get_package_info
Get detailed information about the lodash packageTell me about the vite package including GitHub stats and download numbersget_downloads
How many downloads does react have in the last week?Show me download statistics for next for the last monthget_usage_snippet
Show me a usage example for axiosHow do I use the commander package? Give me a code snippet.get_package_versions
List all versions of React from the last yearShow me the version history of TypeScript since 6 months agoget_package_dependencies
What dependencies does express have?Show me the dependency tree for next with depth 2compare_packages
Compare react, vue, and angularCompare the packages axios, fetch, and node-fetch and help me decide which to usesearch_by_keywords
Find packages with keywords "react" AND "hooks" AND "typescript"Search for packages with keywords "cli" OR "terminal"Combined queries
You can also ask your AI assistant to use multiple tools together:
Compare react-query, swr, and apollo-client, then show me usage examples for the most popular oneSearch for typescript validation libraries, then show me the README and dependencies for the top resultFind the package "zod", show me its download stats, version history, and a usage exampleLicense & Contributing
NPMLens MCP is MIT licensed. Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Found a bug or have a feature request? Open an issue on GitHub.
Made with ❤️ for the vibe coding community. Happy coding!
Available Tools
9 toolscompare_packagesA
Compare multiple npm packages side-by-side (downloads, stars, license, etc.).
Inputs: packages (required).
get_downloadsB
Get npm downloads for the last day/week/month.
Inputs: name (required), period.
get_package_dependenciesC
Get the dependency tree for a package.
Inputs: name (required), depth, version, includeDevDependencies.
get_package_infoA
Get enriched package info: registry metadata, last-week downloads, and GitHub repo details when available.
Inputs: name (required), version, includeReadme.
get_package_versionsA
List all available versions of a package with publish dates and dist tags.
Inputs: name (required), limit, since.
get_readmeA
Fetch README text for a given npm package (optionally a specific version).
Inputs: name (required), version, truncateAt.
get_usage_snippetB
Extract a likely usage snippet from a package's README.
Inputs: name (required), version.
search_by_keywordsB
Search npm packages by specific keywords/tags.
Inputs: keywords (required), size, operator.
search_npmB
Search the npm registry for packages.
Inputs: query (required), from, size, weights.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools have clearly distinct purposes, but search_npm and search_by_keywords could be confused since both are search-related. The descriptions differentiate them (general search vs. keyword/tag search), but the overlap is minor.
All tools follow a consistent verb_noun snake_case pattern (e.g., search_npm, get_package_info, compare_packages). Naming is predictable and clear.
With 9 tools, the set is well-scoped for an npm package analysis server. Each tool addresses a distinct need without being excessive.
The tool surface covers the main lifecycle of npm package research: search, info retrieval, downloads, versions, dependencies, and comparison. No significant gaps are apparent for read-only package analysis.
Maintenance
Related MCP Connectors
Dive into the world of npm with our NPM Package Info MCP. Access crucial metadata about any npm
Live npm and UNPKG data for AI agents: resolution, audits, import maps, malware/CVE checks.
Package intelligence for AI agents across npm, PyPI, crates.io and deps.dev. No API keys.
Package intelligence for AI agents across npm, PyPI, crates.io and deps.dev. No API keys.
Related MCP Servers
- AlicenseDqualityDmaintenanceA Model Context Protocol server that allows AI models to fetch detailed information about npm packages and discover popular packages in the npm ecosystem.16 npm1ISC
- AlicenseAqualityDmaintenanceProvides comprehensive contextual information about npm packages including README files, versions, dependencies, download statistics, and search functionality. Enables users to explore and analyze npm packages through natural language queries with intelligent GitHub README fetching and branch fallback.9MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to search PyPI packages and retrieve detailed metadata, version history, and download statistics. It provides a standardized interface for interacting with the Python Package Index through the Model Context Protocol.2-
- AlicenseNot gradedqualityDmaintenanceProvides a tool to fetch npm package information via the Model Context Protocol.8Apache 2.0