{
  "markdown": "# Blacksmith MCP\n\n[![npm version](https://img.shields.io/npm/v/blacksmith-mcp.svg)](https://www.npmjs.com/package/blacksmith-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)\n\nAn MCP server that connects Claude to your [Blacksmith CI](https://blacksmith.sh) data. Query workflow runs, analyze test failures, detect flaky tests, and monitor usage—all through natural conversation.\n\n## Why?\n\nDebugging CI failures usually means clicking through dashboards, copying run IDs, and piecing together information across multiple pages. With this MCP, you can just ask:\n\n- *\"Why did the last CI run fail?\"*\n- *\"Which tests are flaky this week?\"*\n- *\"Compare test failures between main and my PR\"*\n- *\"What's using the most cache storage?\"*\n\nClaude handles the API calls and gives you actionable insights.\n\n## Quick Start\n\n**Zero-config if you're logged into Blacksmith in Chrome:**\n\n```bash\n# Add to Claude Code\nclaude mcp add blacksmith -- npx blacksmith-mcp\n\n# Set your org (run once)\nexport BLACKSMITH_ORG=\"your-org-name\"\n```\n\nThe MCP automatically extracts your session from Chrome cookies. No manual token copying needed.\n\n## Installation\n\n### Option 1: Claude Code CLI\n\n```bash\nclaude mcp add blacksmith -- npx blacksmith-mcp\n```\n\n### Option 2: Project Configuration\n\nAdd to your `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"blacksmith\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"blacksmith-mcp\"],\n      \"env\": {\n        \"BLACKSMITH_ORG\": \"your-org-name\"\n      }\n    }\n  }\n}\n```\n\n### Option 3: Global Install\n\n```bash\nnpm install -g blacksmith-mcp\n```\n\n## Configuration\n\n### Authentication\n\n**Automatic (recommended):** Log into [app.blacksmith.sh](https://app.blacksmith.sh) in Chrome. The MCP extracts your session cookie automatically.\n\n**Manual:** Set `BLACKSMITH_SESSION_COOKIE` environment variable with your session cookie value.\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `BLACKSMITH_ORG` | Yes | Your Blacksmith organization name |\n| `BLACKSMITH_SESSION_COOKIE` | No | Session cookie (auto-extracted from Chrome if not set) |\n\n## Available Tools\n\n### Workflow Runs\n\n| Tool | Description |\n|------|-------------|\n| `list_runs` | List workflow runs with filters (status, branch, workflow, actor, PR) |\n| `get_run` | Get run details including all jobs |\n| `list_jobs` | List jobs for a workflow run |\n| `get_job` | Get job details (steps, timing, runner info) |\n| `get_job_logs` | Get raw log output for a job |\n\n### Test Analytics\n\n| Tool | Description |\n|------|-------------|\n| `get_job_tests` | Get all test results for a job |\n| `get_failed_tests` | Get failed tests with full error messages |\n| `get_failures_by_pattern` | Group failures by error pattern (e.g., \"Cannot read properties\") |\n| `compare_test_runs` | Compare failures between two runs (find regressions) |\n| `get_flaky_tests` | Detect tests that fail intermittently |\n| `get_slow_tests` | Find tests exceeding duration threshold |\n| `get_test_history` | Track a specific test's pass/fail history |\n| `get_trends` | Analyze trends: duration, failure rate, test count |\n\n### Usage & Billing\n\n| Tool | Description |\n|------|-------------|\n| `get_current_usage` | Current core usage (active vs max) |\n| `get_invoice_amount` | Current billing period amount |\n| `get_usage_summary` | Billable minutes vs free tier |\n| `get_cache_stats` | Cache size, entries by repository |\n| `get_cache_entries` | Detailed cache entries for a repo |\n\n### Organization\n\n| Tool | Description |\n|------|-------------|\n| `list_orgs` | List accessible organizations |\n| `get_org_status` | Org status (personal, onboarded, region) |\n| `search_logs` | Search logs across all jobs |\n\n## Example Conversations\n\n### Debug a Failed Run\n\n> **You:** Why did the last CI run fail?\n>\n> **Claude:** *Uses `list_runs(status=\"failure\", limit=1)` then `get_failed_tests`*\n>\n> The last run failed with 34 test failures. The main issues are:\n> - **Connection timeout** (12 tests) - Tests in `api/` are timing out connecting to the test database\n> - **Undefined property** (8 tests) - `user.settings.theme` is undefined in the new dark mode code\n> - **Assertion failures** (14 tests) - Snapshot mismatches in UI components\n\n### Find Flaky Tests\n\n> **You:** Which tests are flaky?\n>\n> **Claude:** *Uses `get_flaky_tests(days=7, min_runs=5)`*\n>\n> Found 3 flaky tests:\n> | Test | Flake Rate | Pattern |\n> |------|------------|---------|\n> | `should handle concurrent requests` | 40% (4/10 runs) | Fails on CI, passes locally |\n> | `renders loading state` | 20% (2/10 runs) | Race condition with setTimeout |\n> | `validates auth token` | 30% (3/10 runs) | Intermittent network timeout |\n\n### Compare Branches\n\n> **You:** Did my PR introduce new test failures?\n>\n> **Claude:** *Uses `compare_test_runs` with PR run vs base branch*\n>\n> Your PR introduced 2 new failures:\n> - `UserProfile.test.tsx`: \"Cannot read property 'avatar' of undefined\"\n> - `api/users.test.ts`: Expected 200, got 404\n>\n> 5 previously failing tests now pass (nice!).\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build\npnpm build\n\n# Development mode (watch)\npnpm dev\n\n# Test with MCP Inspector\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\n## Troubleshooting\n\n### Session Expired\n\nIf you see `SESSION_EXPIRED`, your Blacksmith session has expired. Simply log back into [app.blacksmith.sh](https://app.blacksmith.sh) in Chrome and retry.\n\n### Cookie Extraction Failed\n\nThe automatic cookie extraction requires:\n- macOS with Chrome installed\n- Being logged into Blacksmith in Chrome\n- Chrome not running with a locked profile\n\nIf it fails, set `BLACKSMITH_SESSION_COOKIE` manually.\n\n### No Organization Set\n\nRun `list_orgs` to see available organizations, then set `BLACKSMITH_ORG` to your org name.\n\n## API Notes\n\nThis MCP uses Blacksmith's internal web API, which is undocumented. The API was reverse-engineered from the Blacksmith web app and may change without notice.\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please open an issue first to discuss proposed changes.\n",
  "bytes": 6259,
  "sha": "e0fea504ed4e7c1b53a5312a58da5d2a8f18e46529b7d9a1d3d7c15f23691bb4",
  "repo_slug": "grahamnotgrant/blacksmith-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_grahamnotgrant_blacksmith_48b94944/readme"
}