projectpulse-mcp
ProjectPulse MCP is a GitHub repository health monitoring server for AI assistants, providing health scores, security checks, CI/CD status, and delivery metrics.
get_health_score: Computes a 0-100 health score with A-F grade, category breakdown, and improvement suggestions.
get_dora_metrics: Calculates proxy DORA metrics (deployment frequency, lead time, change failure rate, MTTR).
compare_repos: Compares health scores of 2-5 repositories and ranks them.
get_repo_health: Returns basic repository metadata (stars, forks, language, license, etc.).
analyze_dependencies: Lists Dependabot security alerts for vulnerable dependencies.
check_ci_status: Shows recent GitHub Actions workflow runs and statuses.
analyze_code_scanning: Lists CodeQL/static analysis alerts, can trigger a scan.
check_best_practices: Audits open-source best practices (README, LICENSE, templates, etc.) with a score.
ping: Simple connectivity check.
Supports stdio and HTTP transports; requires GitHub token for private repos and security data.
Provides tools for retrieving Dependabot alerts for a repository, with optional severity filtering.
Provides tools for analyzing GitHub repository health, including metadata, security alerts, CI/CD status, and an overall health score.
Provides tools for checking recent GitHub Actions workflow runs and their conclusions for a repository.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@projectpulse-mcp Check the health score for facebook/react"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This Model Context Protocol (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.
π Table of Contents
Related MCP server: GitBridge
β¨ Features
π₯ Health Score β comprehensive 0-100 score with grade (A-F), category breakdown, and improvement suggestions
π Security β Dependabot alerts blended with OpenSSF Scorecard checks (60/40 weighted)
π DORA Metrics β proxy DORA metrics 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
π Best Practices β 12-point checklist for open-source repo quality (README, LICENSE, SECURITY.md, templates, branch protection, etc.) with A-F grade
πΈ Examples
All screenshots taken live from MCP Inspector.







π‘ Use Cases
Copy-paste these prompts into Claude, Cursor, Windsurf, or any MCP-compatible assistant.
Due Diligence β Library Adoption
"Evaluate whether
facebook/reactis production-ready. Check the health score, security vulnerabilities (Dependabot and CodeQL), and whether the CI pipeline passes consistently."
Tools used: get_health_score, analyze_dependencies, analyze_code_scanning, check_ci_status
Compare Alternatives
"I need to choose between
expressjs/express,fastify/fastify, andkoajs/koa. Compare their health scores and tell me which one has the lowest technical risk."
Tools used: compare_repos
Sprint Review β DORA Metrics
"Calculate the DORA metrics for
vercel/next.jsover the last 30 days. I want to present delivery performance at our sprint review."
Tools used: get_dora_metrics
Trend Monitoring
"Check the health score of
microsoft/vscode. Has it improved or worsened since the last time we checked?"
Tools used: get_health_score (includes trend comparison on repeated calls)
Quick Security Audit
"Run a security audit of
pallets/flask: Dependabot alerts, CodeQL vulnerabilities, and CI build status. Give me a complete picture."
Tools used: analyze_dependencies, analyze_code_scanning, check_ci_status
π Prerequisites
Node.js v18 or later β download
npm (included with Node.js)
GitHub Personal Access Token (optional for public repos, required for private repos and security data)
π Quick Start
Claude Code (CLI)
claude mcp add projectpulse -- npx projectpulse-mcpNote: You need a
.envfile with yourGITHUB_TOKENin the directory where you run Claude Code.
Claude Desktop
Step 1: Get a GitHub Token
Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens
Give it a name (e.g.,
projectpulse)Select the repositories you want to monitor (or "All repositories")
Under Permissions, grant Read-only access to:
Code scanning alertsDependabot alertsMetadata(enabled by default)
Click Generate token and copy it
Step 2: Configure Claude Desktop
Open Claude Desktop
Go to Settings (gear icon) > Developer > Edit Config
This opens
claude_desktop_config.json. Add theprojectpulseentry inside"mcpServers":
{
"mcpServers": {
"projectpulse": {
"command": "npx",
"args": ["-y", "projectpulse-mcp"],
"env": {
"GITHUB_TOKEN": "ghp_paste_your_token_here"
}
}
}
}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 |
Dependabot/CodeQL data missing | Your token needs |
| Install Node.js (v18 or later) and make sure |
Other MCP Clients (Cursor, Windsurf, etc.)
Configure a new MCP server with:
Transport:
stdioCommand:
npxArguments:
-y projectpulse-mcpEnvironment:
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.
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 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?"
check_best_practices
Evaluates whether a repository follows open-source community best practices. Runs 12 weighted checks: README, LICENSE, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT, issue/PR templates, branch protection, Dependabot config, CI/CD workflows, description, and topics. Returns a 0-100 weighted score with A-F grade, per-check pass/fail/unknown status, and actionable suggestions for every missing item. Branch protection check requires admin token access β returns "unknown" (not penalized) if unavailable.
Inputs: owner, repo
Try asking: "Does my-org/my-repo follow open-source best practices?"
ping
Simple connectivity check. Returns "pong" with your message. Use to verify the MCP server is running.
Inputs: message
π What's New
HTTP Transport (v1.7.0)
ProjectPulse now supports Streamable HTTP transport in addition to stdio. This enables running as a standalone HTTP server β ideal for Docker containers, remote deployments, and cross-runtime integrations (e.g., .NET clients consuming Node.js MCP tools over the network).
Default behavior is unchanged β npx projectpulse-mcp still uses stdio. To activate HTTP mode:
MCP_TRANSPORT=http MCP_PORT=3000 node dist/index.jsEnv Variable | Default | Description |
|
| Transport mode: |
|
| HTTP server port (only used when |
Docker example:
projectpulse:
image: node:22-slim
command: >-
sh -c "npm install -g projectpulse-mcp &&
node /usr/local/lib/node_modules/projectpulse-mcp/dist/index.js"
environment:
- MCP_TRANSPORT=http
- MCP_PORT=3000
- GITHUB_TOKEN=${GITHUB_TOKEN}Health check endpoint available at GET / (returns JSON with server name and version). MCP protocol endpoint at POST /mcp.
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 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.
π Compatibility
ProjectPulse works with any MCP-compatible client. Tested with:
Client | Transport | Status |
stdio | β Tested | |
stdio | β Tested | |
stdio | β Tested | |
stdio | β Tested | |
stdio | β Tested | |
Docker / Remote | HTTP | β Tested |
Any MCP client | stdio or HTTP | β Compatible |
ποΈ Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Client β
β (Claude, Cursor, Windsurf, etc.) β
ββββββββββββββββββββββ¬βββββββββββββββββββββββββββββ
β stdio or HTTP
ββββββββββββββββββββββΌβββββββββββββββββββββββββββββ
β ProjectPulse MCP Server β
β β
β βββββββββββββββ βββββββββββββββ β
β β Tool Layer β β Transport β β
β β (8 tools) β β stdio/HTTP β β
β ββββββββ¬βββββββ βββββββββββββββ β
β β β
β ββββββββΌβββββββ βββββββββββββββ β
β β GitHub API β β OpenSSF β β
β β (Octokit) β β Scorecard β β
β βββββββββββββββ βββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββTool layer: 8 independent tools, each in its own file (
src/tools/)GitHub API: all calls through a shared Octokit client (
src/github/client.ts) with rate-limit handlingOpenSSF Scorecard: integrated via public API for security scoring
Input validation: Zod schemas at the MCP boundary
Transport: stdio (default) or Streamable HTTP β configurable via environment variables
π’ Transport Modes
stdio (default) | HTTP | |
Activation |
|
|
Best for | Local MCP clients | Docker, remote, cross-runtime |
Health check | N/A |
|
MCP endpoint | stdin/stdout |
|
Config needed | None |
|
See What's New: HTTP Transport for Docker examples.
βοΈ Configuration
GITHUB_TOKEN
Required to avoid rate limits and access security data (Dependabot, CodeQL alerts).
Option A: Fine-grained PAT (Recommended)
Settings > Developer settings > Personal access tokens > Fine-grained tokens
Select target repositories
Grant Read-only access to:
Code scanning alertsDependabot alertsMetadata(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
.envfile:GITHUB_TOKEN=ghp_your_token_here
π§ͺ Testing
All 8 tools have dedicated test suites. Tests use Vitest with mocked GitHub API responses.
# Run all tests
npm test
# Watch mode
npm run test:watchTool | Test file | Status |
|
| β |
|
| β |
|
| β |
|
| β |
|
| β |
|
| β |
|
| β |
|
| β |
π€ Author
π€ Contributing
Contributions, issues, and feature requests are welcome!
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Run tests (
npm test) and ensure they passCommit your changes
Push to the branch and open a Pull Request
See the issues page for open tasks and bug reports.
β Show your support
Give a star if this project helped you!
π License
MIT β see the LICENSE file for details.
Available Tools
8 toolsanalyze_code_scanningARead-onlyIdempotent
Fetches or triggers open Code Scanning alerts from all tools (CodeQL, Scorecard, third-party) for a GitHub repository. Note: trigger_scan is CodeQL-only.
Side effects: Read-only by default. If trigger_scan=true (CodeQL-only), writes to GitHub Actions by creating a workflow_dispatch event.
Data sources: GitHub REST API (code-scanning/alerts and actions).
Auth requirements: Requires GITHUB_TOKEN with appropriate permissions (security-events).
Rate limits: Subject to standard GitHub API limits.
Return shape: Returns a JSON array of alert objects including tool_name, rule_id, severity (error/warning/note), security_severity_level (critical/high/medium/low as in GitHub UI, or null), rule_description, state, location paths, and html_url.
Usage guidelines: Use this tool ONLY for deep static analysis code vulnerability scanning. DO NOT use this tool for other checks:
For package/dependency vulnerabilities, use 'analyze_dependencies' instead.
For a computed A-F health score grading, use 'get_health_score' instead.
For checking standard CI/CD workflow statuses, use 'check_ci_status' instead.
Inputs: repo (required), owner (required), trigger_scan, poll_timeout_seconds, +1 more. Returns: alerts, warning
analyze_dependenciesARead-onlyIdempotent
Fetches Dependabot alerts for a GitHub repository to analyze vulnerable package dependencies.
Side effects: None. This is a strictly read-only operation.
Data sources: GitHub REST API (dependabot/alerts).
Auth requirements: Requires GITHUB_TOKEN with appropriate permissions (dependabot alerts are often restricted).
Rate limits: Subject to standard GitHub API limits.
Return shape: Returns a JSON array of vulnerable package dependencies including summary, severity, package_name, state, and html_url.
Usage guidelines: Use this tool ONLY to find vulnerable package dependencies (npm, pip, etc.). DO NOT use this tool for other checks:
For static code security vulnerabilities (CodeQL), use 'analyze_code_scanning' instead.
For a computed A-F health score grading, use 'get_health_score' instead.
Inputs: repo (required), owner (required), severity. Returns: alerts
check_best_practicesARead-onlyIdempotent
Checks whether a GitHub repository follows open-source community best practices.
Evaluates 12 checks: README, LICENSE, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT, issue/PR templates, branch protection, Dependabot, CI/CD, description, and topics.
Returns a weighted 0-100 score with A-F grade, per-check pass/fail/unknown status, and actionable suggestions for missing items.
Side effects: None. Read-only operation.
Rate limits: ~6 GitHub API calls per invocation.
Branch protection check requires admin access β returns "unknown" (not penalized) if token lacks permission.
Use this tool to audit repo quality and discoverability. For a computed health grade based on CI/security/activity, use 'get_health_score' instead.
Inputs: repo (required), owner (required). Returns: repo, grade, score, checks, +6 more
check_ci_statusARead-onlyIdempotent
Fetches recent CI/CD workflow runs (GitHub Actions) for a GitHub repository.
Side effects: None. This is a strictly read-only operation.
Data sources: GitHub REST API (actions/runs).
Auth requirements: No authentication required for public repositories. Uses configured token if available.
Rate limits: Subject to standard GitHub API limits.
Return shape: Returns a JSON array of workflow runs including name, status, conclusion, head_branch, created_at, updated_at, and html_url.
Usage guidelines: Use this tool ONLY to check raw GitHub Actions workflow history and CI build statuses. DO NOT use this tool for other analyses:
For a computed A-F health score grading, use 'get_health_score' instead.
For retrieving basic repository stats (stars, forks), use 'get_repo_health' instead.
For calculated DORA metrics, use 'get_dora_metrics' instead.
Inputs: repo (required), owner (required), limit. Returns: runs
compare_reposARead-onlyIdempotent
Compares health scores of multiple GitHub repositories (2-5 repos) and ranks them.
Side effects: None. This is a strictly read-only operation.
Data sources: GitHub REST API and OpenSSF Scorecard API (via get_health_score logic).
Auth requirements: No authentication required for public repositories. Uses configured token if available.
Rate limits: Subject to standard GitHub API limits. Multiplies API calls by the number of repositories compared.
Return shape: Returns a JSON object containing a ranked list of repositories (owner, repo, rank) with their detailed health breakdown (score, CI, freshness, security, community, maintenance).
Usage guidelines: Use this tool ONLY when you need to compare or rank multiple repositories against each other based on their health scores. DO NOT use this tool for analyzing a single repository:
For getting the health score of a single repository, use 'get_health_score' instead.
For comparing raw metadata instead of health scores, query 'get_repo_health' individually.
Inputs: repos (required). Returns: repos, compared_at
get_dora_metricsARead-onlyIdempotent
Calculates DORA proxy metrics (deployment frequency, lead time, change failure rate, MTTR) for a GitHub repository.
Side effects: None. This is a strictly read-only operation.
Data sources: GitHub REST API (releases, actions/runs, pulls).
Auth requirements: No special authentication required for public repositories. Private repositories require GITHUB_TOKEN.
Rate limits: Subject to standard GitHub API limits. Heavy API usage due to multiple list endpoints being queried.
Return shape: Returns a JSON object with calculated DORA metrics over the specified period.
Usage guidelines: Use this tool ONLY to evaluate DORA metrics and team delivery performance. DO NOT use this tool for other checks:
For raw workflow statuses, use 'check_ci_status' instead.
For a computed A-F health score grading, use 'get_health_score' instead.
For general repository metadata, use 'get_repo_health' instead.
Inputs: repo (required), owner (required), days. Returns: mttr, repo, owner, lead_time, +5 more
get_health_scoreAIdempotent
Calculates a 0-100 health score and A-F grade for a GitHub repository.
Side effects: Writes a trend snapshot to local disk for history tracking. Read-only against GitHub API.
Data sources: GitHub REST API (repos, actions, dependabot) and OpenSSF Scorecard API.
Auth requirements: No authentication required for public repositories. Uses configured token if available.
Rate limits: Subject to standard GitHub API limits (heavy usage across multiple endpoints).
Return shape: Returns a JSON object with a grade (A-F), total score, detailed category breakdown (CI, freshness, security, community, maintenance), improvement suggestions, historical trend data, and an 'openssf' object containing official score, securityChecksAverage, and individual 'checks' (worst score first).
Usage guidelines: Use this tool ONLY for deep analytical grading and overall repository health assessment. DO NOT use this tool for quick metadata checks:
For basic raw metadata (stars, language, etc.), use 'get_repo_health' instead.
For raw CI workflow statuses, use 'check_ci_status' instead.
For deep code vulnerability scanning, use 'analyze_code_scanning' instead.
For DORA metrics, use 'get_dora_metrics' instead.
Inputs: repo (required), owner (required). Returns: trend, report, openssf, badgeSnippet, +1 more
get_repo_healthARead-onlyIdempotent
Fetches basic repository metadata and statistics from the public GitHub API.
Side effects: None. This is a strictly read-only operation.
Data sources: Public GitHub REST API (GET /repos/{owner}/{repo}).
Auth requirements: No authentication required for public repositories. Uses configured GitHub token if available.
Rate limits: Subject to standard GitHub API limits (60 requests/hour unauthenticated, 5000 requests/hour authenticated).
Return shape: Returns a JSON object containing specific metadata: full_name (string), description (string), stargazers_count (number), open_issues_count (number), language (string), license (string, SPDX ID), pushed_at (ISO 8601 string), default_branch (string), archived (boolean), and forks_count (number).
Usage guidelines: Use this tool ONLY to retrieve basic raw metadata (like stars, forks, language, and issue counts). DO NOT use this tool for other specific analyses:
For a computed A-F health score grading, use 'get_health_score' instead.
For checking CI/CD workflow run statuses, use 'check_ci_status' instead.
For package vulnerabilities and dependency graph, use 'analyze_dependencies' instead.
For code security and static analysis, use 'analyze_code_scanning' instead.
Inputs: repo (required), owner (required). Returns: license, archived, language, full_name, +6 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 8 tools
Each tool targets a distinct analysis area, and the descriptions include explicit 'DO NOT use this for X, use Y instead' guidance that sharply delineates boundaries. However, get_health_score and check_best_practices both emit a 0-100 score with an A-F grade, and compare_repos is essentially a multi-repo wrapper of get_health_score, so a few tools could still be confused at the edges.
All eight tools use snake_case with a clear verb_noun structure (analyze_*, get_*, check_*, compare_*). The verb prefixes are chosen sensibly for each operation and the convention is applied uniformly across the set.
Eight tools is well-scoped for a repository health/analysis server, with each tool covering a distinct facet (metadata, CI, DORA, dependencies, code scanning, best practices, health score, comparison). No tool appears redundant or padded.
The surface covers a broad analysis lifecycle: raw metadata, CI status, DORA metrics, dependency and code-scanning alerts, best-practice audit, aggregated health scoring, and multi-repo comparison. Minor gaps remain, such as no way to retrieve historical trend snapshots or drill into individual alert details, but core workflows are well covered.
Maintenance
Related MCP Connectors
Evaluates any GitHub repository for license risk, maintenance velocity, stars/forks, and security.
Evaluates any GitHub repository for license risk, maintenance velocity, stars/forks, and supply-c.
Screens public GitHub repos and PRs to generate risk maps, findings, and merge-readiness signals.
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Related MCP Servers
- AlicenseCqualityDmaintenanceMonitors and analyzes GitHub repository health by detecting stale branches, old pull requests, unresponsive issues, and security alerts. Integrates with MCP-compatible AI assistants and automation tools.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to analyze GitHub repositories, including fetching repository details, searching, and retrieving README content.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to analyze GitHub repositories with tools for health scoring, contributor analysis, issue tracking, code search, and more.MIT
- FlicenseAqualityCmaintenanceEnables real-time assessment of GitHub repository health by exposing tools and resources for repository metadata, open issues, recent commits, and GitHub Actions workflow runs, plus prompts for health reports and issue triage.4-