packagelens-mcp

`packagelens-mcp` lets your coding agent (such as Claude, Cursor, Copilot,

Gemini or Codex) search package registries across multiple ecosystems

(npm, PyPI, RubyGems, Crates.io, Packagist, Hex) and fetch package context

(README, downloads, GitHub info, usage snippets). It features **smart

ecosystem auto-detection**, so your AI can find packages without needing

to specify which ecosystem to search. 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 | Example Queries | Troubleshooting | Tool reference

Supported Ecosystems

PackageLens MCP supports 6 package ecosystems with varying feature availability:

\* *PyPI does not provide an official downloads API*

Key features

• 🌟 Smart ecosystem auto-detection - Ask "Find HTTP clients"

without specifying npm, PyPI, etc.

• 🔍 Multi-ecosystem support: npm, PyPI, RubyGems, Crates.io,

Packagist, Hex

• 📦 Structured package search with optional ranking weights
• 📄 Direct README fetch (optionally truncated)
• 📊 Enriched package info (downloads + GitHub details)
• 🔖 Version listing and dependency analysis
• 💡 Usage snippet extraction from README
• 🔌 Stdio MCP transport, ready for MCP‑compatible clients

Disclaimers

`packagelens-mcp` performs network requests to package registries (npm, PyPI,

RubyGems, Crates.io, Packagist, Hex) 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": {
    "packagelens": {
      "command": "npx",
      "args": ["-y", "packagelens-mcp@latest"]
    }
  }
}

> [!NOTE]

> Using `packagelens-mcp@latest` ensures your MCP client always runs the

> latest published version.

MCP Client configuration

Amp

Follow the Amp docs and use the config provided above. You can also

install via CLI:

amp mcp add packagelens -- npx packagelens-mcp@latest

Claude Code

Use the Claude Code CLI to add the PackageLens MCP server (see the Claude

Code MCP guide):

claude mcp add packagelens npx packagelens-mcp@latest

Cline

Follow and use the

config provided above.

Codex

Use the Codex CLI to add the server:

codex mcp add packagelens -- npx packagelens-mcp@latest

Copilot CLI

Start Copilot CLI:

copilot

Start the dialog to add a new MCP server by running:

/mcp add

Configure the following fields and press `CTRL+S` to save:

• Server name: `packagelens`
• Server Type: `Local`
• Command: `npx -y packagelens-mcp@latest`

Copilot / VS Code

Use the VS Code CLI:

code --add-mcp '{"name":"packagelens","command":"npx","args":["-y","packagelens-mcp@latest"]}'

Cursor

Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.

Gemini CLI

Install the PackageLens MCP server using the Gemini CLI.

Project wide:

gemini mcp add packagelens npx packagelens-mcp@latest

Globally:

gemini mcp add -s user packagelens npx packagelens-mcp@latest

Alternatively, follow the Gemini CLI MCP guide and use the standard

config from above.

Gemini Code Assist

Follow the provider guide to configure MCP servers and use the

standard config from above.

JetBrains AI Assistant & Junie

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

Warp

Go to `Settings | AI | Manage MCP Servers` -> `+ Add` and use the

config provided above.

Your first prompt

Enter one of these smart queries (no ecosystem needed!) to check if

everything works:

Smart search (auto-detects ecosystems):

Find HTTP client libraries

Find async runtime packages for Rust

Smart package info (auto-detects ecosystem):

Tell me about react

Get info for django including README

Smart usage examples:

Show me how to use axios

Compare packages:

Compare react-query, swr, and apollo-client

Advanced: Ecosystem-specific queries (when you need control):

Search npm for React debounce hooks, show weekly downloads

What are the dependencies of express in npm? 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.md` for all technical details.
• See `CONTRIBUTING.md` for contributing guidelines.

Tools

PackageLens MCP provides 8 tools with automatic ecosystem detection.

For full JSON schemas, see the

Tool reference.

🌟 Primary Tool: `smart_search`

The main tool you'll use for finding packages. It automatically detects

which package ecosystem to search based on your project or query.

Detection Strategy:

1. Query keywords - Detects language mentions (Python, Rust, JavaScript, etc.)

2. Codebase analysis - Checks current directory for package files

(package.json → npm, Cargo.toml → Crates.io, etc.)

3. User clarification - If still unclear, asks for specification

Args: `query`, `ecosystem?`, `packageName?`, `size?`

Important: Once an ecosystem is detected, the response includes a directive

to use `ecosystem="..."` parameter in ALL follow-up searches to maintain

consistency. Do NOT search other ecosystems unless explicitly requested.

Examples:

// In a TypeScript project with package.json
{ query: "HTTP clients" }
// → Auto-detects npm, searches npm only

// Follow-up query (maintaining consistency)
{ query: "async libraries", ecosystem: "npm" }
// → Continues searching npm

// Explicit ecosystem
{ query: "web frameworks", ecosystem: "pypi" }
// → Searches PyPI regardless of project type

// With language context
{ query: "Find Rust async runtime libraries" }
// → Detects "Rust", searches Crates.io

Other Smart Tools

All smart tools support an optional `ecosystem` parameter for explicit

specification.

Package Information:

• `smart_package_info` - Get detailed package info
  • Args: `packageName`, `ecosystem?`, `context?`, `includeReadme?`
  • Example: "Tell me about react" → detects npm

• `smart_get_readme` - Fetch package README
  • Args: `packageName`, `ecosystem?`, `context?`, `version?`, `truncateAt?`
  • Example: "Get README for django" → detects PyPI

• `smart_get_usage_snippet` - Extract code examples from README
  • Args: `packageName`, `ecosystem?`, `context?`, `version?`
  • Example: "Show me how to use axios" → detects npm

Versions & Dependencies:

• `smart_get_versions` - List package versions
  • Args: `packageName`, `context?`, `limit?`, `since?`
  • Example: "Show versions of tokio" → detects Crates.io

• `smart_get_dependencies` - Get package dependencies
  • Args: `packageName`, `context?`, `version?`
  • Example: "What does express depend on?" → detects npm

Downloads:

• `smart_get_downloads` - Get download statistics
  • Args: `packageName`, `context?`, `period?`
  • Example: "How many downloads does flask have?" → detects PyPI

Comparison:

• `compare_packages` - Compare packages across ecosystems
  • Args: `items[]` with `{ecosystem, name}` objects
  • Example: Compare axios (npm), requests (PyPI), httparty (RubyGems)

Sample usage queries

PackageLens MCP supports two query styles: smart queries (automatic

detection) and specific queries (explicit ecosystem). Once an ecosystem

is detected, use the same ecosystem for follow-up queries to maintain

consistency.

🌟 Smart Queries (Automatic Detection)

Initial search with language context:

Find Python HTTP client libraries
→ Detects PyPI from "Python" keyword
→ Response: "Use ecosystem='pypi' for follow-up searches"

Search for Rust async libraries
→ Detects Crates.io from "Rust" keyword
→ Response: "Use ecosystem='crates' for follow-up searches"

Initial search in project directory:

Find HTTP client libraries
→ In TypeScript project with package.json
→ Detects npm from codebase
→ Response: "Use ecosystem='npm' for follow-up searches"

Search for async runtime packages
→ In Rust project with Cargo.toml
→ Detects Crates.io from codebase
→ Response: "Use ecosystem='crates' for follow-up searches"

Follow-up searches (maintaining consistency):

Initial: "Find Python web frameworks"
→ Detects PyPI, finds django, flask, fastapi

Follow-up: "Show me more async frameworks" (with ecosystem='pypi')
→ Continues searching PyPI only
→ Finds aiohttp, starlette, tornado

Initial: "Search for JavaScript testing libraries"
→ Detects npm, finds jest, mocha, vitest

Follow-up: "Find assertion libraries" (with ecosystem='npm')
→ Continues searching npm only
→ Finds chai, expect, should

Package info with auto-detection:

Tell me about react
→ Detects npm from well-known package name

Get info for django including README
→ Detects PyPI from well-known package name

Show me details for tokio
→ Detects Crates.io from well-known package name

Usage examples:

Show me how to use axios
→ Detects npm, extracts usage snippet from README

Get usage example for requests
→ Detects PyPI, extracts usage snippet from README

Versions and dependencies:

What versions of react are available?
→ Detects npm, lists recent versions

What does express depend on?
→ Detects npm, shows dependency tree

Downloads:

How many downloads does django have?
→ Detects PyPI (note: PyPI doesn't provide download stats)

Show me weekly downloads for lodash
→ Detects npm, shows weekly download count

Cross-ecosystem comparison (explicit intent):

Compare axios from npm with requests from PyPI
→ Compares HTTP clients across ecosystems

Compare react, vue, and angular
→ All detected as npm packages, compares within npm

🎯 Specific Queries (Explicit Ecosystem)

Use these when you need precise control or want to override auto-detection:

Explicit ecosystem search:

Search npm for React debounce hooks
→ Uses npm regardless of project type

Search crates for tokio alternatives
→ Uses Crates.io regardless of project type

Maintaining consistency with explicit parameter:

Initial: "Find web frameworks" (in TypeScript project)
→ Detects npm

Follow-up: Search for "validation libraries" with ecosystem="npm"
→ Continues in npm (recommended approach)

Switching ecosystems (when needed):

Initial: "Find Python web frameworks"
→ Detects PyPI, finds django, flask

Explicit switch: "Now search npm for web frameworks"
→ Explicitly switches to npm ecosystem

Specific package queries:

Get info for @types/node from npm
→ Scoped package, explicitly npm

Show README for symfony/console from packagist
→ Vendor/package format, explicitly Packagist

Advanced dependency queries:

What are the dependencies of express in npm? Include dev dependencies.
→ Explicit npm query with dev dependencies

Show me versions of tokio from crates published in last 6 months
→ Explicit crates query with time filter

💡 Best Practices

1. First query: Use language context ("Python", "Rust") or let

codebase detection work

2. Follow-up queries: Use the `ecosystem` parameter from the first

response

3. Comparisons: Only compare across ecosystems when explicitly

comparing alternatives

4. Specific packages: Well-known package names auto-detect reliably

(react → npm, django → PyPI)

License & Contributing

PackageLens 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!