packagelens-mcp

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:

Ecosystem	Search	README	Versions	Dependencies	Downloads
npm	✅	✅	✅	✅	✅
RubyGems (Ruby)	✅	✅	✅	✅	✅
Crates.io (Rust)	✅	✅	✅	✅	✅
Packagist (PHP)	✅	✅	✅	✅	✅
Hex (Elixir)	✅	✅	✅	✅	✅
PyPI (Python)	✅	✅	✅	✅	❌*

* 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: ```bash 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): ```bash claude mcp add packagelens npx packagelens-mcp@latest ```

Cline

Follow <https://docs.cline.bot/mcp/configuring-mcp-servers> and use the config provided above.

Codex

Use the Codex CLI to add the server: ```bash codex mcp add packagelens -- npx packagelens-mcp@latest ```

Copilot CLI

Start Copilot CLI: ```bash copilot ``` Start the dialog to add a new MCP server by running: ```bash /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: ```bash 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:** ```bash gemini mcp add packagelens npx packagelens-mcp@latest ``` **Globally:** ```bash 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!

This site is open source. Improve this page.