# Gaffer

MCP server connecting AI assistants to Gaffer test history. It checks flaky tests, coverage gaps, and failure clusters directly during debugging.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 1
- Author: gaffer-sh
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/gaffer-sh/mcp
- Updated: 2026-08-11
- HTML: https://affpapa.org/en/nevibecode/mcp/gaffer

## What it does

The server links your coding assistant to test analytics stored in Gaffer. It groups failures by root causes, isolates flaky checks with high flip rates, and flags files that combine low coverage with recent test breaks. Out of 17 available functions, 16 are strictly read-only; only `upload_test_results` writes data.

To save context space, the server runs in code mode. Rather than exposing dozens of standalone MCP tools, it provides just three: `execute_code`, `search_tools`, and `list_projects`. The assistant chains analytics calls inside a small JavaScript snippet under the `codemode` namespace. Each execution has a 30-second timeout and a cap of 20 API calls.

Without an active Gaffer account holding test results and a valid `GAFFER_API_KEY`, the server cannot retrieve anything. You also need a user key starting with `gaf_` to inspect project lists.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `GAFFER_API_KEY`, `GAFFER_API_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env GAFFER_API_KEY=<GAFFER_API_KEY> --env GAFFER_API_URL=<GAFFER_API_URL> --transport stdio gaffer -- npx -y @gaffer-sh/mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add gaffer --env GAFFER_API_KEY=<GAFFER_API_KEY> --env GAFFER_API_URL=<GAFFER_API_URL> -- npx -y @gaffer-sh/mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "gaffer": {
            "command": "npx",
            "args": [
                "-y",
                "@gaffer-sh/mcp"
            ],
            "env": {
                "GAFFER_API_KEY": "<GAFFER_API_KEY>",
                "GAFFER_API_URL": "<GAFFER_API_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "gaffer": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@gaffer-sh/mcp"
            ],
            "env": {
                "GAFFER_API_KEY": "<GAFFER_API_KEY>",
                "GAFFER_API_URL": "<GAFFER_API_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e GAFFER_API_KEY=<GAFFER_API_KEY> -e GAFFER_API_URL=<GAFFER_API_URL> gaffer npx -y @gaffer-sh/mcp
```
Replace <…> with your own values

## When to use it
- Identify flaky tests with frequent pass-fail flips
- Group test failures by root cause
- Find files combining poor test coverage with failures
- Compare test metrics between git commits

## Example prompts
- Check our project test health and list the flakiest tests
- Compare test durations and pass rates between the last two commits
- Find untested files that also experienced recent test failures

## Similar
- [check-coverage](https://affpapa.org/en/nevibecode/skills/check-coverage.md) — skill · ★ 243
- [test-reliability](https://affpapa.org/en/nevibecode/skills/test-reliability.md) — skill · 1100 installs
- [fix-flaky-tests](https://affpapa.org/en/nevibecode/skills/fix-flaky-tests.md) — skill · 503 installs
- [debugging](https://affpapa.org/en/nevibecode/skills/akillness-debugging.md) — skill · 361 installs
- [Trunk Flaky Tests](https://affpapa.org/en/nevibecode/mcp/trunk-flaky-tests.md) — MCP server
- [flaky-test-triage](https://affpapa.org/en/nevibecode/commands/flaky-test-triage.md) — command · 24 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md