blacksmith-usage-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BLACKSMITH_ORG | No | Your GitHub org slug for Blacksmith.sh usage. Optional; can be passed as argument to tools. | |
| BLACKSMITH_SESSION_FILE | No | Path to a file containing the session JSON. Defaults to ${XDG_CONFIG_HOME:-~/.config}/blacksmith-usage-mcp/session.json. | |
| BLACKSMITH_SESSION_JSON | No | Full session JSON inline. Handy for CI/headless, where you inject a cookie harvested elsewhere. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| blacksmith_whoamiA | Who the stored Blacksmith session belongs to (verifies auth is live). |
| blacksmith_list_orgsA | List GitHub orgs/installations available to the session. |
| blacksmith_cost_summaryB | Headline cost for a month: total jobs, billable minutes, and dollar cost. |
| blacksmith_cost_dailyB | Per-day breakdown of jobs, minutes, and cost for a month. |
| blacksmith_cost_by_repoC | Cost broken down by repository for a month. |
| blacksmith_cost_by_runnerA | Cost broken down by runner type (e.g. blacksmith-4vcpu-ubuntu-2404) for a month. |
| blacksmith_sticky_disk_costB | Sticky-disk (Docker cache) storage cost and GB-hours for a month. Often the largest line item. |
| blacksmith_monthly_usageB | Billable vs included-free minutes for a month (free-tier headroom). |
| blacksmith_current_vcpuA | Live vCPU/job usage right now, by architecture (null when idle). |
| blacksmith_vcpu_timeseriesC | vCPU/job usage time series for a month (windowed). Large payload. |
| blacksmith_cost_overviewA | One-shot cost report for a month: totals, free-tier headroom, sticky-disk, and the top repos + runner types by cost. |
| blacksmith_sticky_disk_dailyA | Daily sticky-disk / Docker-layer-cache footprint (GB held each day) for a month — the cache growth curve. Steadily-climbing totals mean an unbounded cache (set max-cache-size-mb on setup-docker-builder); a flat line means a stable working set. |
| blacksmith_cost_trendA | Month-over-month compute vs sticky-disk cost for the last N months — spots accumulating cache cost vs one-off compute spikes. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 13 tools
Most tools have a clear, distinct purpose (e.g., cost_daily vs cost_by_repo vs cost_by_runner). However, cost_summary and cost_overview overlap in providing headline totals, which could cause an agent to pick the wrong one for a simple total-cost query.
The blacksmith_ prefix is consistent, and most names follow a <domain>_<granularity> pattern (cost_summary, cost_daily, vcpu_timeseries). Minor deviations exist: list_orgs uses a verb while others are noun phrases, and whoami is a standalone command, but the overall pattern is predictable.
13 tools is well-scoped for a usage/cost monitoring server. Each tool covers a distinct reporting dimension (summary, daily, by repo, by runner, sticky disk, live usage, trends) without redundancy or bloat.
The surface covers the full lifecycle of Blacksmith usage reporting: auth, orgs, compute cost, free-tier allowance, live vCPU, sticky-disk cost and growth, and month-over-month trends. There are no obvious dead ends or critical missing operations for the stated purpose.