\n GitHub repository health monitoring for AI assistants โ works with any language, any repo.\n
\n\n
\n \n \n \n \n \n \n
\n\n---\n\nThis [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.\n\n## โจ Features\n\n- ๐ฅ **Health Score** โ comprehensive 0-100 score with grade (A-F), category breakdown, and improvement suggestions\n- ๐ **Security** โ Dependabot alerts blended with [OpenSSF Scorecard](https://scorecard.dev/) checks (60/40 weighted)\n- ๐ **DORA Metrics** โ proxy [DORA metrics](https://dora.dev/) from GitHub data: deployment frequency, lead time, change failure rate, MTTR\n- ๐ **Code Scanning** โ CodeQL and other code scanning alerts with severity, message, and creation date\n- ๐ฆ **Dependency Analysis** โ Dependabot alerts with severity filtering\n- โ๏ธ **CI/CD Status** โ recent GitHub Actions workflow runs and conclusions\n- ๐ **Repository Info** โ stars, forks, language, license, and general metadata\n\n## ๐ธ Example\n\n### MCP Inspector โ `get_repo_health`\n\n\n\n### Code Scanning โ `analyze_code_scanning`\n\n\n\n## ๐ Quick Start\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add projectpulse -- npx projectpulse-mcp\n```\n\n> **Note:** You need a `.env` file with your `GITHUB_TOKEN` in the directory where you run Claude Code.\n\n### Claude Desktop\n\n#### Step 1: Get a GitHub Token\n\n1. Go to [GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens](https://github.com/settings/personal-access-tokens/new)\n2. Give it a name (e.g., `projectpulse`)\n3. Select the repositories you want to monitor (or \"All repositories\")\n4. Under **Permissions**, grant **Read-only** access to:\n - `Code scanning alerts`\n - `Dependabot alerts`\n - `Metadata` (enabled by default)\n5. Click **Generate token** and copy it\n\n#### Step 2: Configure Claude Desktop\n\n1. Open Claude Desktop\n2. Go to **Settings** (gear icon) > **Developer** > **Edit Config**\n3. This opens `claude_desktop_config.json`. Add the `projectpulse` entry inside `\"mcpServers\"`:\n\n```json\n{\n \"mcpServers\": {\n \"projectpulse\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"projectpulse-mcp\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"ghp_paste_your_token_here\"\n }\n }\n }\n}\n```\n\n4. Save the file and **restart Claude Desktop**\n\n#### Step 3: Verify it works\n\nIn a new Claude Desktop conversation, try asking:\n\n> \"Check the health score of facebook/react\"\n\nClaude should call the `get_health_score` tool and return an A-F grade with a detailed breakdown.\n\n#### Troubleshooting\n\n| Problem | Solution |\n| --- | --- |\n| Tools not showing up | Restart Claude Desktop after editing the config file |\n| \"Rate limit exceeded\" errors | Make sure `GITHUB_TOKEN` is set correctly in the config |\n| Dependabot/CodeQL data missing | Your token needs `Code scanning alerts` and `Dependabot alerts` permissions |\n| `npx` not found | Install [Node.js](https://nodejs.org/) (v18 or later) and make sure `npx` is in your PATH |\n\n### Other MCP Clients (Cursor, Windsurf, etc.)\n\nConfigure a new MCP server with:\n- **Transport**: `stdio`\n- **Command**: `npx`\n- **Arguments**: `-y projectpulse-mcp`\n- **Environment**: `GITHUB_TOKEN` = your GitHub PAT\n\n## ๐ ๏ธ Tools\n\n### `get_health_score`\nCalculates 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/).\n\n**Side effect:** saves a trend snapshot to local disk (`~/.projectpulse/snapshots/`).\n\n**Inputs:** `owner`, `repo`\n**Try asking:** *\"What's the health score of microsoft/vscode?\"*\n\n### `get_dora_metrics`\nCalculates 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.\n\n**Inputs:** `owner`, `repo`, `days` (optional, 7-90, default 30)\n**Try asking:** *\"Show me the DORA metrics for vercel/next.js over the last 60 days\"*\n\n### `compare_repos`\nCompares 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.\n\n**Inputs:** `repos` (array of `{owner, repo}`)\n**Try asking:** *\"Compare the health of expressjs/express, fastify/fastify, and koajs/koa\"*\n\n### `get_repo_health`\nFetches **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.\n\n**Inputs:** `owner`, `repo`\n**Try asking:** *\"Give me general info about torvalds/linux\"*\n\n### `analyze_dependencies`\nLists **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.\n\n**Inputs:** `owner`, `repo`, `severity` (optional)\n**Try asking:** *\"Show me critical dependency vulnerabilities in my-org/my-app\"*\n\n### `check_ci_status`\nReturns 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.\n\n**Inputs:** `owner`, `repo`, `limit` (optional, default 10)\n**Try asking:** *\"Are the CI builds passing for facebook/react?\"*\n\n### `analyze_code_scanning`\nLists **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).\n\n**Inputs:** `owner`, `repo`, `trigger_scan` (optional, default `false`), `poll_timeout_seconds` (optional, default 300), `poll_interval_seconds` (optional, default 15)\n**Try asking:** *\"Are there any code scanning vulnerabilities in my-org/my-api?\"*\n\n### `ping`\nSimple connectivity check. Returns \"pong\" with your message. Use to verify the MCP server is running.\n\n**Inputs:** `message`\n\n## ๐ What's New\n\n### OpenSSF Scorecard Integration\n\nSecurity 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.\n\n### DORA Metrics\n\nNew `get_dora_metrics` tool calculates proxy [DORA metrics](https://dora.dev/) from public GitHub data:\n\n| Metric | Source | Unit |\n| --- | --- | --- |\n| Deployment Frequency | Releases | releases/week |\n| Lead Time for Changes | PR created โ merged | hours (median) |\n| Change Failure Rate | CI workflow conclusions | percentage |\n| Mean Time to Recovery | CI failure โ next success | hours (median) |\n\nMetrics return `null` when insufficient data is available โ works safely on any repository.\n\n## โ๏ธ Configuration\n\n### GITHUB_TOKEN\n\nRequired to avoid rate limits and access security data (Dependabot, CodeQL alerts).\n\n**Option A: Fine-grained PAT (Recommended)**\n1. **Settings** > **Developer settings** > **Personal access tokens** > **Fine-grained tokens**\n2. Select target repositories\n3. Grant **Read-only** access to:\n - `Code scanning alerts`\n - `Dependabot alerts`\n - `Metadata` (default)\n\n**Option B: Classic Token**\nGenerate with `repo` + `security_events` scopes.\n\n**Providing the token:**\n- **Claude Desktop**: set in `claude_desktop_config.json` (see Quick Start)\n- **Claude Code / Local**: create a `.env` file:\n ```env\n GITHUB_TOKEN=ghp_your_token_here\n ```\n\n## ๐ค Author\n\n**alexbypa** โ [GitHub](https://github.com/alexbypa) ยท [npm](https://www.npmjs.com/~alexbypa)\n\n## ๐ค Contributing\n\nContributions, issues and feature requests are welcome!\nFeel free to check the [issues page](https://github.com/alexbypa/github-projectpulse-mcp/issues).\n\n## โญ Show your support\n\nGive a star if this project helped you!\n\n## ๐ License\n\nMIT โ see the [LICENSE](LICENSE) file for details.\n",
"bytes": 10254,
"sha": "1f4db5cf99b3dce1d720d1042272cd5ea9cd3a06a740e7a20794c926b46ec998",
"repo_slug": "alexbypa/github-projectpulse-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_alexbypa_github_projectpulse_m_3f25b45e/readme"
}
![\"npm](\"https://img.shields.io/npm/v/projectpulse-mcp.svg?color=blue\")
\n ![\"license\"](\"https://img.shields.io/github/license/alexbypa/github-projectpulse-mcp\")
\n ![\"tests\"](\"https://img.shields.io/github/actions/workflow/status/alexbypa/github-projectpulse-mcp/ci.yml?label=tests\")
\n ![\"stars\"](\"https://img.shields.io/github/stars/alexbypa/github-projectpulse-mcp\")
\n ![\"downloads\"](\"https://img.shields.io/npm/dt/projectpulse-mcp\")
\n ![\"OpenSSF](\"https://img.shields.io/ossf-scorecard/github.com/alexbypa/github-projectpulse-mcp?label=openssf+scorecard\")
\n