Gaffer MCP Server

@gaffer-sh/mcp

MCP (Model Context Protocol) server for Gaffer - give your AI assistant memory of your tests.

What is this?

This MCP server connects AI coding assistants like Claude Code and Cursor to your Gaffer test history and coverage data. It allows AI to:

• Check your project's test health (pass rate, flaky tests, trends)
• Look up the history of specific tests to understand stability
• Get context about test failures when debugging
• Analyze code coverage and identify untested areas
• Browse all your projects (with user API Keys)
• Access test report files (HTML reports, coverage, etc.)

Prerequisites

1. A Gaffer account with test results uploaded
2. An API Key from Account Settings > API Keys

Setup

Claude Code (CLI)

The easiest way to add the Gaffer MCP server is via the Claude Code CLI:

claude mcp add gaffer -e GAFFER_API_KEY=gaf_your_api_key_here -- npx -y @gaffer-sh/mcp

Claude Code (Manual)

Alternatively, add to your Claude Code settings (~/.claude.json or project .claude/settings.json):

{
  "mcpServers": {
    "gaffer": {
      "command": "npx",
      "args": ["-y", "@gaffer-sh/mcp"],
      "env": {
        "GAFFER_API_KEY": "gaf_your_api_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "gaffer": {
      "command": "npx",
      "args": ["-y", "@gaffer-sh/mcp"],
      "env": {
        "GAFFER_API_KEY": "gaf_your_api_key_here"
      }
    }
  }
}

Available Tools

Project & Test Run Tools

Test Analysis Tools

Upload & Status Tools

Coverage Tools

Tool Details

`list_projects`

List all projects you have access to.

• Input: organizationId (optional), limit (optional, default: 50)
• Returns: List of projects with IDs, names, and organization info
• Example: "What projects do I have in Gaffer?"

`get_project_health`

Get the health metrics for a project.

• Input: projectId (required), days (optional, default: 30)
• Returns: Health score (0-100), pass rate, test run count, flaky test count, trend
• Example: "What's the health of my test suite?"

`get_test_history`

Get the pass/fail history for a specific test.

• Input: projectId (required), testName or filePath (one required), limit (optional)
• Returns: History of runs with status, duration, branch, commit, errors
• Example: "Is the login test flaky? Check its history"

`get_flaky_tests`

Get the list of flaky tests in a project.

• Input: projectId (required), threshold (optional, default: 0.1), days (optional), limit (optional)
• Returns: List of flaky tests with flip rates, transition counts, run counts
• Example: "Which tests are flaky in my project?"

`list_test_runs`

List recent test runs with optional filtering.

• Input: projectId (required), commitSha (optional), branch (optional), status (optional), limit (optional)
• Returns: List of test runs with pass/fail/skip counts, commit and branch info
• Example: "What tests failed in the last commit?"

`get_test_run_details`

Get parsed test results for a specific test run.

• Input: testRunId (required), projectId (required), status (optional filter), limit (optional)
• Returns: Individual test results with name, status, duration, file path, errors
• Example: "Show me all failed tests from this test run"

`get_report`

Get URLs for report files uploaded with a test run.

• Input: testRunId (required)
• Returns: List of files with filename, size, content type, do