# ProjectPulse MCP **Category:** ๐Ÿ“Š Monitoring **Repository:** https://github.com/alexbypa/github-projectpulse-mcp **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/projectpulse-mcp ## Description Monitor GitHub repo health, DORA metrics and CI signals from your AI assistant. ## Claude Desktop Quick Installation Heuristic fallback โ€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "projectpulse-mcp": { "command": "npx", "args": ["-y","projectpulse-mcp"] } } ``` ## Documentation & README

ProjectPulse MCP ๐Ÿฅ

GitHub repository health monitoring for AI assistants โ€” works with any language, any repo.

npm version license tests stars downloads OpenSSF Scorecard

--- This [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server gives AI assistants the ability to analyze health, security, CI/CD status, and delivery metrics of any GitHub repository โ€” directly from your conversations. ## โœจ Features - ๐Ÿฅ **Health Score** โ€” comprehensive 0-100 score with grade (A-F), category breakdown, and improvement suggestions - ๐Ÿ”’ **Security** โ€” Dependabot alerts blended with [OpenSSF Scorecard](https://scorecard.dev/) checks (60/40 weighted) - ๐Ÿ“Š **DORA Metrics** โ€” proxy [DORA metrics](https://dora.dev/) from GitHub data: deployment frequency, lead time, change failure rate, MTTR - ๐Ÿ” **Code Scanning** โ€” CodeQL and other code scanning alerts with severity, message, and creation date - ๐Ÿ“ฆ **Dependency Analysis** โ€” Dependabot alerts with severity filtering - โš™๏ธ **CI/CD Status** โ€” recent GitHub Actions workflow runs and conclusions - ๐Ÿ“‹ **Repository Info** โ€” stars, forks, language, license, and general metadata ## ๐Ÿ“ธ Example ### MCP Inspector โ€” `get_repo_health` ![MCP Inspector Demo](https://raw.githubusercontent.com/alexbypa/github-projectpulse-mcp/main/docs/images/projectpulse-inspector-demo.png) ### Code Scanning โ€” `analyze_code_scanning` ![Code Scanning Example](https://raw.githubusercontent.com/alexbypa/github-projectpulse-mcp/main/docs/images/code-scanning-example.png) ## ๐Ÿš€ Quick Start ### Claude Code (CLI) ```bash claude mcp add projectpulse -- npx projectpulse-mcp ``` > **Note:** You need a `.env` file with your `GITHUB_TOKEN` in the directory where you run Claude Code. ### Claude Desktop #### Step 1: Get a GitHub Token 1. Go to [GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens](https://github.com/settings/personal-access-tokens/new) 2. Give it a name (e.g., `projectpulse`) 3. Select the repositories you want to monitor (or "All repositories") 4. Under **Permissions**, grant **Read-only** access to: - `Code scanning alerts` - `Dependabot alerts` - `Metadata` (enabled by default) 5. Click **Generate token** and copy it #### Step 2: Configure Claude Desktop 1. Open Claude Desktop 2. Go to **Settings** (gear icon) > **Developer** > **Edit Config** 3. This opens `claude_desktop_config.json`. Add the `projectpulse` entry inside `"mcpServers"`: ```json { "mcpServers": { "projectpulse": { "command": "npx", "args": ["-y", "projectpulse-mcp"], "env": { "GITHUB_TOKEN": "ghp_paste_your_token_here" } } } } ``` 4. Save the file and **restart Claude Desktop** #### Step 3: Verify it works In a new Claude Desktop conversation, try asking: > "Check the health score of facebook/react" Claude should call the `get_health_score` tool and return an A-F grade with a detailed breakdown. #### Troubleshooting | Problem | Solution | | --- | --- | | Tools not showing up | Restart Claude Desktop after editing the config file | | "Rate limit exceeded" errors | Make sure `GITHUB_TOKEN` is set correctly in the config | | Dependabot/CodeQL data missing | Your token needs `Code scanning alerts` and `Dependabot alerts` permissions | | `npx` not found | Install [Node.js](https://nodejs.org/) (v18 or later) and make sure `npx` is in your PATH | ### Other MCP Clients (Cursor, Windsurf, etc.) Configure a new MCP server with: - **Transport**: `stdio` - **Command**: `npx` - **Arguments**: `-y projectpulse-mcp` - **Environment**: `GITHUB_TOKEN` = your GitHub PAT ## ๐Ÿ› ๏ธ Tools ### `get_health_score` Calculates a **0-100 health score** with an A-F grade. Evaluates 5 weighted categories: CI reliability (25%), code freshness (20%), security posture (25%), community activity (15%), and maintenance quality (15%). Returns actionable improvement suggestions for low-scoring categories. On repeated calls for the same repo, includes a **trend comparison** showing score change since last check. Queries multiple GitHub API endpoints and [OpenSSF Scorecard](https://scorecard.dev/). **Side effect:** saves a trend snapshot to local disk (`~/.projectpulse/snapshots/`). **Inputs:** `owner`, `repo` **Try asking:** *"What's the health score of microsoft/vscode?"* ### `get_dora_metrics` Calculates proxy [DORA metrics](https://dora.dev/) from public GitHub data: **Deployment Frequency** (from releases), **Lead Time for Changes** (PR created โ†’ merged), **Change Failure Rate** (CI failure percentage), and **Mean Time to Recovery** (CI failure โ†’ next success). Returns `null` for metrics with insufficient data. Queries multiple GitHub API endpoints (releases, pulls, actions) โ€” heavier API usage than single-endpoint tools. **Inputs:** `owner`, `repo`, `days` (optional, 7-90, default 30) **Try asking:** *"Show me the DORA metrics for vercel/next.js over the last 60 days"* ### `compare_repos` Compares health scores **side-by-side** for 2-5 repositories. Returns each repo's full health breakdown ranked by score. Useful for evaluating alternatives or benchmarking your project against similar ones. API calls are multiplied by the number of repos compared. **Inputs:** `repos` (array of `{owner, repo}`) **Try asking:** *"Compare the health of expressjs/express, fastify/fastify, and koajs/koa"* ### `get_repo_health` Fetches **basic repository metadata**: stars, forks, open issues count, primary language, license, last push date, default branch, and archive status. Use this for a quick overview โ€” for a computed grade, use `get_health_score` instead. **Inputs:** `owner`, `repo` **Try asking:** *"Give me general info about torvalds/linux"* ### `analyze_dependencies` Lists **Dependabot security alerts** for vulnerable package dependencies (npm, pip, Maven, etc.) grouped by severity (critical, high, medium, low). Optionally filter by a specific severity level. Requires a token with `Dependabot alerts` permission. **Inputs:** `owner`, `repo`, `severity` (optional) **Try asking:** *"Show me critical dependency vulnerabilities in my-org/my-app"* ### `check_ci_status` Returns the **most recent CI/CD workflow runs** from GitHub Actions: status (success, failure, in_progress), conclusion, branch, duration, and timestamps. Useful for checking if builds are green before deploying or merging. **Inputs:** `owner`, `repo`, `limit` (optional, default 10) **Try asking:** *"Are the CI builds passing for facebook/react?"* ### `analyze_code_scanning` Lists **CodeQL and other code scanning alerts**: rule ID, severity, vulnerability message, affected file and line number, and creation date. Requires a token with `Code scanning alerts` permission. Can optionally **trigger a CodeQL scan** and wait for results (requires Advanced Setup, not Default Setup). **Inputs:** `owner`, `repo`, `trigger_scan` (optional, default `false`), `poll_timeout_seconds` (optional, default 300), `poll_interval_seconds` (optional, default 15) **Try asking:** *"Are there any code scanning vulnerabilities in my-org/my-api?"* ### `ping` Simple connectivity check. Returns "pong" with your message. Use to verify the MCP server is running. **Inputs:** `message` ## ๐Ÿ†• What's New ### OpenSSF Scorecard Integration Security score now blends **Dependabot alerts** (60%) with **OpenSSF Scorecard** checks (40%) for a more complete picture. 12 security-relevant checks are evaluated โ€” repos without a scorecard gracefully fall back to Dependabot-only scoring. ### DORA Metrics New `get_dora_metrics` tool calculates proxy [DORA metrics](https://dora.dev/) from public GitHub data: | Metric | Source | Unit | | --- | --- | --- | | Deployment Frequency | Releases | releases/week | | Lead Time for Changes | PR created โ†’ merged | hours (median) | | Change Failure Rate | CI workflow conclusions | percentage | | Mean Time to Recovery | CI failure โ†’ next success | hours (median) | Metrics return `null` when insufficient data is available โ€” works safely on any repository. ## โš™๏ธ Configuration ### GITHUB_TOKEN Required to avoid rate limits and access security data (Dependabot, CodeQL alerts). **Option A: Fine-grained PAT (Recommended)** 1. **Settings** > **Developer settings** > **Personal access tokens** > **Fine-grained tokens** 2. Select target repositories 3. Grant **Read-only** access to: - `Code scanning alerts` - `Dependabot alerts` - `Metadata` (default) **Option B: Classic Token** Generate with `repo` + `security_events` scopes. **Providing the token:** - **Claude Desktop**: set in `claude_desktop_config.json` (see Quick Start) - **Claude Code / Local**: create a `.env` file: ```env GITHUB_TOKEN=ghp_your_token_here ``` ## ๐Ÿ‘ค Author **alexbypa** โ€” [GitHub](https://github.com/alexbypa) ยท [npm](https://www.npmjs.com/~alexbypa) ## ๐Ÿค Contributing Contributions, issues and feature requests are welcome! Feel free to check the [issues page](https://github.com/alexbypa/github-projectpulse-mcp/issues). ## โญ Show your support Give a star if this project helped you! ## ๐Ÿ“ License MIT โ€” see the [LICENSE](https://github.com/alexbypa/github-projectpulse-mcp/blob/HEAD/LICENSE) file for details.