github-projectpulse-mcp

ProjectPulse MCP is a GitHub repository health monitoring tool, provided as a Model Context Protocol (MCP) server, allowing AI assistants to directly analyze the health, security, CI/CD status, and delivery metrics of any GitHub repository within a conversation, supporting any language and any repository.

Purpose It is intended for scenarios that require quickly assessing the quality and risk of GitHub repositories within a conversation, such as: library selection due diligence (determining whether a project can be put into production), solution comparison (comparing the technical risks of multiple candidate repositories), sprint retrospectives (displaying DORA metrics), trend monitoring (comparing the historical health scores of the same repository), and quick security audits (dependency alerts, code scanning, and CI status).

Main capabilities (8 tools)

• get_health_score: Calculates a 0-100 health score and gives an A-F grade, evaluating 5 weighted dimensions: CI reliability 25%, code freshness 20%, security posture 25%, community activity 15%, maintenance quality 15%; provides actionable improvement suggestions for low-scoring dimensions; when repeatedly called for the same repository, it returns a trend comparison with the last check. Queries multiple GitHub API endpoints and OpenSSF Scorecard. Side effect: saves trend snapshots to local disk (~/.projectpulse/snapshots/). Input: owner, repo.
• get_dora_metrics: Infers proxy DORA metrics from public GitHub data: deployment frequency (from releases), lead time for changes (PR creation to merge), change failure rate (CI failure percentage), mean time to recovery (CI failure to next success). Metrics with insufficient data return null. Queries multiple GitHub API endpoints (releases, pulls, actions); API usage is higher than single-endpoint tools. Input: owner, repo, days (optional, 7-90, default 30).
• compare_repos: Compares the health scores of 2-5 repositories side by side, returns the complete health details of each repository sorted by score, suitable for evaluating alternatives or benchmarking against similar projects. The number of API calls multiplies with the number of repositories. Input: repos (array of {owner, repo}).
• get_repo_health: Retrieves basic repository metadata: stars, forks, number of unresolved issues, primary language, license, last push date, default branch, archived status. For a computed rating, use get_health_score instead. Input: owner, repo.
• analyze_dependencies: Lists Dependabot security alerts (npm, pip, Maven, etc.), grouped by severity (critical, high, medium, low), and can be filtered by a specified severity level. Requires a token with Dependabot alerts permission. Input: owner, repo, severity (optional).
• check_ci_status: Returns the most recent GitHub Actions workflow runs: status (success, failure, in_progress), conclusion, branch, duration, and timestamp, suitable for checking whether the build passes before deployment or merging. Input: owner, repo, limit (optional, default 10).
• analyze_code_scanning: Lists CodeQL and other code scanning alerts: rule ID, severity, vulnerability message, affected file and line number, creation date. Requires a token with Code scanning alerts permission. Optionally triggers a CodeQL scan and waits for results (requires Advanced Setup, not Default Setup). Input: owner, repo, trigger_scan (optional, default false), poll_timeout_seconds (optional, default 300), poll_interval_seconds (optional, default 15).
• check_best_practices: Evaluates whether a repository follows open source community best practices, running 12 weighted checks: README, LICENSE, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT, issue/PR templates, branch protection, Dependabot configuration, CI/CD workflows, description, and topics. Returns a 0-100 weighted score with an A-F grade, pass/fail/unknown status for each item, and actionable recommendations for each missing item. The branch protection check requires admin token permission; when unavailable, it returns "unknown" and does not deduct points. Input: owner, repo. There is also ping: a simple connectivity check that returns "pong" with your message, used to verify that the MCP server is running. Input: message.

Usage Prerequisites: Node.js v18 or higher, npm (provided with Node.js), GitHub Personal Access Token (optional for public repositories, required for private repositories and security data).

• Claude Code (CLI): Requires a .env file containing GITHUB_TOKEN in the directory where Claude Code is running.
• Claude Desktop: Open Settings (gear icon) > Developer > Edit Config, edit claude_desktop_config.json, add a projectpulse entry under "mcpServers", save, and restart.
• Other MCP clients (Cursor, Windsurf, etc.): Configure a new MCP server, with Transport as stdio, Arguments as -y projectpulse-mcp, and the environment variable GITHUB_TOKEN set to your GitHub PAT.
• HTTP transport (v1.7.0): In addition to stdio, a Streamable HTTP transport has been added, which can run as a standalone HTTP server, suitable for Docker containers, remote deployments, and cross-runtime integration. The default behavior is unchanged; npx projectpulse-mcp still uses stdio; activate HTTP mode via an environment variable. The health check endpoint is GET / (returns JSON containing the server name and version), and the MCP protocol endpoint is POST /mcp. Token permissions: A Fine-grained PAT is recommended. In Settings > Developer settings > Personal access tokens > Fine-grained tokens, select the target repository and grant read-only permissions for Code scanning alerts, Dependabot alerts, and Metadata (enabled by default). You can also use a token with Classic token with repo + security_events scopes.

Use cases

• Repository due diligence: assess whether a repository is ready for production, checking health score, security vulnerabilities, and whether CI passes consistently.
• Compare alternatives: compare health scores across multiple candidate repositories to find the one with the lowest technical risk.
• Sprint retrospective: calculate a project's DORA metrics for the last 30 days.
• Trend monitoring: repeatedly check a repository's health score to observe improvement or deterioration.
• Quick security audit: summarize Dependabot alerts, CodeQL vulnerabilities, and CI build status.

Compatibility and architecture Can be used with any MCP-compatible client. Architecturally, the tool layer consists of 8 independent tools, each occupying one file under src/tools/; all calls go through a shared Octokit client (src/github/client.ts) and handle rate limiting; OpenSSF Scorecard is integrated via a public API for security scoring; input validation uses Zod schemas at the MCP boundary; the transport is stdio (default) or Streamable HTTP, configurable via environment variables.

Limitations

• A GitHub token is required to avoid rate limiting and access security data (Dependabot, CodeQL alerts).
• get_dora_metrics is a proxy metric based on public GitHub data; when data is insufficient, the corresponding metric returns null.
• The trigger scan feature for code scanning requires Advanced Setup, not Default Setup.
• Branch protection checks require admin token permissions; when unavailable, they return "unknown" and do not deduct points.
• get_health_score saves trend snapshots to local disk.
• Tests use Vitest with mocked GitHub API responses.

License and support: MIT License, see the LICENSE file for details. The author is alexbypa, and it is published both in the repository and on npm. Contributions, issues, and feature requests are welcome.