Apache Health MCP

This repo contains a small MCP server for querying the Apache Incubator health reports from tools/health/reports.

It parses the Markdown report format used by Apache's health tooling and exposes MCP tools for:

listing available podling reports
searching podling names
getting a parsed summary for one podling
returning the raw Markdown report
returning metrics for one specific window
comparing one podling across two or three windows
listing supported metrics and windows
ranking podlings by a metric within a window like 3m, 6m, or 12m

Expected input

Point the server at a local directory containing Markdown files like:

reports/
  Amoro.md
  Iggy.md
  ...

The parser is designed around the current Apache report structure, especially the ## Window Details section.

Install

python -m venv .venv
source .venv/bin/activate
pip install -e .

For local development:

make install-dev

Run

apache-health-mcp --reports-dir /path/to/incubator/tools/health/reports

Or launch the stdio server directly, the same way PodlingsMCP is structured:

python3 server.py

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add:

{
  "mcpServers": {
    "apache-health": {
      "command": "python3",
      "args": [
        "/Users/yourname/HealthMCP/server.py",
        "--reports-dir",
        "/path/to/incubator/tools/health/reports"
      ]
    }
  }
}

Then restart Claude Desktop. Use absolute paths, and if needed point command at your venv Python instead of plain python3.

MCP tools

health_overviewReturns the reports directory, report count, podling list, and latest generated date.

list_podlingsReturns the podling names available in the reports directory.

search_podlingsSearches podling names by case-insensitive substring with an optional result limit.

get_report_summaryReturns parsed window metrics for a single podling.

get_report_markdownReturns the raw Markdown for a single podling report.

get_window_metricsReturns metrics for one podling and one window such as 3m, 6m, 12m, or to-date, including normalized trend words like up, down, and flat under trends.

compare_windowsReturns side-by-side metrics for one podling across two or three windows, including normalized trend words under each window's trends.

query_metric_rankingsRanks podlings by a parsed metric such as commits, prs_merged, dev_messages, bus50, or median_merge_days.

list_metricsReturns the supported metric names and available windows for querying.

Development

Common tasks are available through make:

make format
make lint
make typecheck
make test
make coverage
make check

Notes

This server queries already-generated report files. It does not run Apache's upstream collection script.
The workspace here did not include a local reports/ directory, so the server is built to accept any local clone or copied snapshot of Apache's reports directory.

Apache Health MCP