Pkg Health MCP

What orcsnren/pkg-health-mcp does

orcsnren/pkg-health-mcp turns dependency maintenance data into a score from 0 to 100, an A–F grade, and a readable explanation of the risks. It covers packages in npm and PyPI, as well as GitHub repositories supplied as owner/repo or a GitHub URL. The result can identify conditions such as deprecation, archived source repositories, stale releases, inactive contributors, or unanswered issues.

The same scoring engine can inspect one dependency, review an entire dependency set, or compare alternatives within an ecosystem. Manifest and lock-file scans can include transitive dependencies, making the server suitable for both package selection and existing-project audits.

How it works

The server exposes three read-only MCP tools:

• check_package scores one npm package, PyPI package, or GitHub repository.
• scan_manifest evaluates dependencies from supported manifests and lock files, then places the riskiest results first.
• compare_packages ranks two to five alternatives from the same registry, or compares GitHub repositories.

Scores combine release and commit recency, active committer counts, maintainer response time, download trends, OpenSSF Scorecard results, and license information. Reports include per-signal details, an overall confidence value, and concrete risk explanations. Missing or unreachable data reduces confidence rather than directly lowering the score.

Supported project files include package.json, requirements.txt, pyproject.toml, package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock, and uv.lock. Git dependencies hosted on GitHub are evaluated as repositories.

Setup and configuration

Node.js 20 or later is required. No global installation is needed; start the MCP server with:

npx -y pkg-health-mcp

Configure that command as a stdio server in an MCP client. The documented configurations cover Claude Code, Claude Desktop, Cursor, and VS Code. Other MCP clients can start the same command if they support stdio transport.

A GitHub token is optional. Set GITHUB_TOKEN or GH_TOKEN to raise the unauthenticated GitHub API limit and enable maintainer-response measurements that require GraphQL access. A fine-grained token with read-only access to public repositories is sufficient. The token is sent to api.github.com.

The server keeps a disk cache shared between runs, with a default lifetime of 12 hours. It also supports local human-readable, JSON, and Markdown output through the related command-line workflow, including threshold-based CI checks and GitHub Action usage.

Tools and capabilities

check_package accepts names such as express, @types/node, or requests, plus GitHub repository identifiers and URLs. The ecosystem can be selected as npm, PyPI, or GitHub, with npm as the default when it cannot be inferred.

scan_manifest is useful for auditing direct and transitive dependencies. compare_packages helps evaluate several candidates before choosing one. All three tools are annotated as read-only and idempotent, so clients can invoke them without confirmation prompts.

The scoring data comes from public package registries, GitHub, download statistics, OpenSSF Scorecard, and license information. The server communicates directly with those public APIs and does not use a hosted backend or telemetry service.

Limitations and notes

GitHub API limits affect how many repositories or GitHub-backed packages can be checked. Without a token, the limit is 60 requests per hour; authenticated access raises it to 5,000. When the limit is reached, registry data can still contribute to scores, with a warning in the report. Cached results can avoid repeated GitHub requests during the cache period.

The health score is a maintenance signal, not a vulnerability scan or a guarantee that a dependency is safe. Confidence indicates how much of the scoring weight is supported by available data. The project is licensed under Apache-2.0.