# blacksmith [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/grahamnotgrant/blacksmith-mcp  
**GitHub Stars:** 6  
**npm Downloads (last month):** 1369  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/blacksmith

## Description
MCP server for Blacksmith CI - query runs, analyze test failures, detect flaky tests.

## Tools
Capabilities this server exposes over MCP:

- **list_orgs** — List all Blacksmith organizations accessible to your account. Use this first to see available orgs.
- **get_org_status** — Get the status of the current organization (personal org, onboarding, runner region).
- **list_runs** — List workflow runs with filtering. Filter by status (success/failure/cancelled/skipped/in_progress), branch, workflow name, actor, or PR number. Example: list_runs(status="failure") to find failed runs.
- **get_run** — Get details of a specific workflow run by ID. Includes list of jobs.
- **list_jobs** — List all jobs for a specific workflow run. Use this to get job IDs for get_job, get_job_logs, and get_job_tests.
- **get_job** — Get details of a specific job including steps, runner info, and timing.
- **get_job_logs** — Get the logs for a specific job. Returns raw log output.
- **get_job_tests** — Get test results for a job. Optionally filter by status (pass/fail/skip).
- **get_failed_tests** — Get failed tests for a job with full error details. Use error_lines param to control stack trace length. Returns all failures by default (no limit).
- **get_failures_by_pattern** — Group failed tests by error pattern (e.g., "is not a function", "Cannot read properties"). Shows count, affected suites/files, and sample error for each pattern. Best for quickly identifying root causes.
- **compare_test_runs** — Compare test failures between two runs to identify regressions. Shows new failures, fixed tests, and persistent failures. If base_run_id not provided, compares against most recent prior run.
- **get_flaky_tests** — Detect flaky tests by analyzing pass/fail patterns across recent runs. Returns tests that fail intermittently (e.g., "failed 3 of 10 runs"). Killer feature for CI stability.
- **get_slow_tests** — Find tests exceeding a duration threshold. Shows slowest tests, their percentage of total test time, and average duration stats.
- **get_test_history** — Get the failure history for a specific test across recent runs. Shows when it passed/failed, on which branches, and error messages for failures.
- **get_trends** — Track metrics over time: duration (are tests getting slower?), failure_rate (are tests getting flakier?), test_count (are we adding tests?). Returns trend analysis with data points.
- **get_current_usage** — Get current core usage snapshot (active cores vs max cores).
- **get_invoice_amount** — Get the current billing period invoice amount.
- **get_usage_summary** — Get usage summary showing billable minutes vs free tier allowance. Shows remaining free minutes and overage.
- **get_cache_stats** — Get Blacksmith cache statistics: total size, hit rate, entries by repository. Shows how effectively caching is being used.
- **get_cache_entries** — Get detailed cache entries for a repository. Shows cache keys, sizes, scopes (branches), and last hit times. Useful for debugging cache issues.
- **search_logs** — Search logs across all jobs. Filter by query (e.g., "error", "timeout"), log level (INFO/WARN/ERROR/DEBUG), and time range. Great for finding issues across runs.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "blacksmith": {
    "command": "npx",
    "args": ["-y","blacksmith-mcp"],
    "env": {
      "BLACKSMITH_ORG": "",
      "BLACKSMITH_SESSION_COOKIE": ""
    }
  }
}
```

**Requires environment variables:** `BLACKSMITH_ORG`, `BLACKSMITH_SESSION_COOKIE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What blacksmith MCP server does

The blacksmith MCP server gives MCP clients access to Blacksmith CI information through a collection of read-oriented tools. It covers workflow runs, jobs, job steps, timing, runner details, raw logs, and test results. Run queries can be filtered by status, branch, workflow, actor, or pull request, while individual runs can be inspected together with their jobs.

Test analysis is a central use case. The available tools can return failed tests with their complete error messages, group failures by recurring error patterns, compare failures between two runs, identify intermittent tests, find tests above a duration threshold, and show the pass/fail history of a named test. Trend analysis includes test duration, failure rate, and test count.

The server also exposes operational information from Blacksmith. You can inspect active and maximum core usage, billing-period charges, billable minutes against the free tier, cache size, repository cache entries, accessible organizations, organization status, and logs searched across all jobs.

## How it works

The server runs as an MCP process and makes requests to Blacksmith's web API on behalf of the connected client. For example, a failure investigation can begin by listing failed runs, continue with run or job details, and then retrieve logs or failed-test information. Comparing two test runs can help identify regressions between a pull-request run and another run.

Authentication normally comes from an active Blacksmith session in Chrome. The process extracts the session cookie rather than requiring the user to copy a token. The automatic method has specific requirements: macOS, Chrome installed, an active login to Blacksmith, and a Chrome profile that is not locked.

## Setup and configuration

Install and launch the blacksmith MCP server with `npx blacksmith-mcp`, either through the Claude Code CLI or an MCP project configuration using the `stdio` transport. A global npm installation is also documented. Set `BLACKSMITH_ORG` to the Blacksmith organization name; the README marks this variable as required. If automatic cookie extraction is unavailable or fails, set `BLACKSMITH_SESSION_COOKIE` to the session cookie value.

When the organization is unknown, use `list_orgs` to view accessible organizations and then assign the selected name to `BLACKSMITH_ORG`. An expired session requires logging into Blacksmith again in Chrome before retrying, unless a valid session cookie is supplied manually.

## Tools and capabilities

Available tool groups include:

- Workflow inspection: `list_runs`, `get_run`, `list_jobs`, `get_job`, and `get_job_logs`.
- Test analysis: `get_job_tests`, `get_failed_tests`, `get_failures_by_pattern`, `compare_test_runs`, `get_flaky_tests`, `get_slow_tests`, `get_test_history`, and `get_trends`.
- Account and infrastructure data: `get_current_usage`, `get_invoice_amount`, `get_usage_summary`, `get_cache_stats`, and `get_cache_entries`.
- Organization and search: `list_orgs`, `get_org_status`, and `search_logs`.

## Limitations and notes

That API may change without notice. Automatic cookie extraction is not presented as a universal option: its documented requirements are limited to macOS with Chrome and an unlocked Chrome profile.

_Full upstream README: https://allmcps.com/mcp/blacksmith/readme_