blacksmith — Claude Code MCP server: what it does, how to install
An MCP server connecting your assistant to Blacksmith CI. It inspects failing runs, surfaces flaky tests, and tracks runner costs without leaving your CLI.
claude mcp add blacksmith -e BLACKSMITH_ORG=<BLACKSMITH_ORG> -e BLACKSMITH_SESSION_COOKIE=<BLACKSMITH_SESSION_COOKIE> -- npx -y blacksmith-mcpWhat blacksmith does
This server pulls workflow diagnostics from Blacksmith CI straight into your coding agent. You bypass opening web dashboards or stitching run identifiers by hand. The toolset covers inspecting workflow runs via list_runs, dumping step logs with get_job_logs, and categorizing failed tests through get_failures_by_pattern. It also handles comparing failure diffs across branches to detect regressions in pull requests.
The server also exposes runner metrics. You can inspect active CPU cores via get_current_usage, view cache size with get_cache_stats, and review billable minutes. On macOS, authentication grabs your active session cookie straight from Chrome. If your browser profile is locked or you run another operating system, you must supply BLACKSMITH_SESSION_COOKIE manually.
The tool talks to an undocumented internal web endpoint. Because the API was reverse-engineered from the Blacksmith web interface, upstream changes might disrupt operations. You must also supply your organization slug in BLACKSMITH_ORG before initiating queries.
What it helps with
- diagnose reasons behind a failed CI workflow run
- pinpoint flaky tests across recent pipeline executions
- spot test regressions introduced in a pull request
- inspect build cache storage and runner core consumption
Example prompts for the agent
- Why did the latest CI run fail in Blacksmith?
- Show me flaky tests from the past seven days.
- Did this PR introduce any new test failures compared to main?
How to install blacksmith
Platform CLI
claude mcp add blacksmith -e BLACKSMITH_ORG=<BLACKSMITH_ORG> -e BLACKSMITH_SESSION_COOKIE=<BLACKSMITH_SESSION_COOKIE> -- npx -y blacksmith-mcpReplace <…> with your own values
Platform CLI
codex mcp add blacksmith --env BLACKSMITH_ORG=<BLACKSMITH_ORG> --env BLACKSMITH_SESSION_COOKIE=<BLACKSMITH_SESSION_COOKIE> -- npx -y blacksmith-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"blacksmith": {
"command": "npx",
"args": [
"-y",
"blacksmith-mcp"
],
"env": {
"BLACKSMITH_ORG": "<BLACKSMITH_ORG>",
"BLACKSMITH_SESSION_COOKIE": "<BLACKSMITH_SESSION_COOKIE>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"blacksmith": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"blacksmith-mcp"
],
"env": {
"BLACKSMITH_ORG": "<BLACKSMITH_ORG>",
"BLACKSMITH_SESSION_COOKIE": "<BLACKSMITH_SESSION_COOKIE>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e BLACKSMITH_ORG=<BLACKSMITH_ORG> -e BLACKSMITH_SESSION_COOKIE=<BLACKSMITH_SESSION_COOKIE> blacksmith npx -y blacksmith-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about blacksmith
How to install blacksmith in Claude Code?
Run claude mcp add blacksmith -e BLACKSMITH_ORG=<BLACKSMITH_ORG> -e BLACKSMITH_SESSION_COOKIE=<BLACKSMITH_SESSION_COOKIE> -- npx -y blacksmith-mcp in your terminal.
What does the blacksmith MCP server do?
It connects AI coding assistants to Blacksmith CI data, enabling run diagnosis, log retrieval, flaky test detection, and billing metric tracking.
How does authentication work for blacksmith?
On macOS, the server extracts session credentials directly from Chrome if you are logged into app.blacksmith.sh. On other environments, specify BLACKSMITH_SESSION_COOKIE alongside BLACKSMITH_ORG manually.
