Blacksmith

You can connect Claude to your Blacksmith CI data with the Blacksmith MCP server. It lets you query workflow runs, analyze test failures, detect flaky tests, and monitor usage through natural conversation, so you get actionable insights without hunting through dashboards.

How to use

Use the Blacksmith MCP to interact with your CI data from Claude. Ask natural questions like “Why did the last CI run fail?” or “Which tests are flaky this week?” and Claude will translate your request into API calls, returning concise results and relevant details. You can inspect run details, review test outcomes, compare failures across branches, and see usage metrics all from a single conversation.

How to install

Prerequisites: you need Node.js installed on your machine. You will also use the Claude Code CLI to add the MCP server.

# Add the Blacksmith MCP to Claude Code
claude mcp add blacksmith -- npx blacksmith-mcp

# Set your organization (run once)
export BLACKSMITH_ORG="your-org-name"

Configuration

Automatic authentication is supported by logging into app.blacksmith.sh in Chrome. The MCP can extract your session, so you don’t need to copy tokens manually.

MCP configuration examples

{
  "mcpServers": {
    "blacksmith": {
      "type": "stdio",
      "command": "npx",
      "args": ["blacksmith-mcp"],
      "env": {
        "BLACKSMITH_ORG": "your-org-name"
      }
    }
  }
}

Environment variables

Required: BLACKSMITH_ORG — your Blacksmith organization name. Optional: you can provide BLACKSMITH_SESSION_COOKIE if you prefer manual authentication. When not provided, the MCP can extract the session cookie automatically from Chrome.

Available tools and capabilities (summary)

The Blacksmith MCP exposes a range of tools to inspect runs, test results, usage, and organization data. You can list and detail runs, fetch job and log information, analyze tests and failures, and view trends and caches. These tools enable you to investigate failures, identify flaky tests, compare runs, and monitor resources across your projects.

Troubleshooting

If you encounter issues with authentication, ensure you are logged into Chrome for Blacksmith and that you have the correct organization name set in BLACKSMITH_ORG. If automatic cookie extraction fails, you can set BLACKSMITH_SESSION_COOKIE manually with your session value.

Development notes

To develop and test locally, install dependencies, build, and run in development mode as described in the project’s standard workflow. You can verify the MCP integration by running your client against the local server and using the inspector tooling for debugging.

Security and data handling

The MCP uses your authenticated Blacksmith data through the internal API endpoints. Access is scoped to your organization, and session tokens or cookies are used to authorize requests. Treat session cookies and tokens as sensitive data and avoid sharing them publicly.

API notes

This MCP relies on Blacksmith’s internal web API for data access. Endpoints and behaviors may change as Blacksmith updates their platform, so expect occasional adjustments in tool outputs and field names.

Available tools

list_runs

List workflow runs with filters such as status, branch, workflow, actor, and PR.

get_run

Get detailed information about a specific run, including all jobs.

list_jobs

List all jobs for a particular workflow run.

get_job

Get details for a single job, including steps and runner information.

get_job_logs

Retrieve the raw log output for a specific job.

get_job_tests

Fetch all test results for a particular job.

get_failed_tests

Return failed tests with full error messages.

get_failures_by_pattern

Group failures by a common error pattern to identify root causes.

compare_test_runs

Compare test failures between two runs to identify regressions.

get_flaky_tests

Detect tests that fail intermittently across runs.

get_slow_tests

Identify tests that exceed a duration threshold.

get_test_history

Track a specific test’s pass/fail history over time.

get_trends

Analyze trends in duration, failure rate, and test count.

get_current_usage

Show current core usage vs. maximum capacity.

get_invoice_amount

Display the current billing period amount.

get_usage_summary

Summarize billable minutes versus the free tier.

get_cache_stats

Provide cache size and entries by repository.

get_cache_entries

Show detailed cache entries for a repository.

list_orgs

List accessible organizations.

get_org_status

Show organization status (personal, onboarded, region).

search_logs

Search logs across all jobs.