# Msha Mines [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/pipeworx-io/mcp-msha-mines  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1042  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/msha-mines

## Description
MSHA mine records — search a US mine by operator or mine name, or look up

## Tools
Capabilities this server exposes over MCP:

- **msha_mine_search** — Search MSHA (Mine Safety and Health Administration) mine records by operator name, controller name, or mine name. Returns matching mines with their MSHA Mine ID, status (Active, Abandoned, Intermittent, etc.), mine type (Surface/Underground/Facility), coal vs metal/non-metal classification, commodity, state, and current operator/controller. Use this to find the Mine ID(s) for a company before calling msha_mine_detail. Sourced from MSHA's own bulk mine-records file (public domain), refreshed weekly. Keyless.
- **msha_mine_detail** — Look up a known MSHA Mine ID: current status, type, commodity, operator and controller, plus recent inspections, recent violations (with assessed penalties, S&S flag, and abatement/termination dates), and recent quarterly employment and coal production. Violations/inspections/production cover only the most recent 5 calendar years (the response says so) — MSHA's full history back to 2000 is not loaded. Sourced from MSHA's own bulk mine-records files (public domain), refreshed weekly. Keyless.
- **msha_violation_counts** — Count MSHA violations issued at one mine within a calendar year or year range — in ONE call, not a listing. Returns the TOTAL plus a breakdown by who it was issued to (Operator vs Contractor vs Agent vs Miner) and by significant-and-substantial (S&S) status. Use this instead of msha_mine_detail when the question is "how many" — msha_mine_detail only returns its most recent violations_limit rows (default 20, max 100) and has no true count. Counted by the calendar year of each violation's own issue date (VIOLATION_ISSUE_DT, via MSHA's own CAL_YR field). Only the most recent 5 calendar years are loaded (the response's `coverage` field says exactly which); a year outside that window comes back flagged as "not loaded," never as a silent zero. Takes a known MSHA Mine ID (use msha_mine_search to find one) or a mine/operator/controller name — the name path only works when it resolves to exactly one mine; otherwise it lists the candidates so you can retry with a mine_id. Sourced from MSHA's own bulk mine-records files (public domain), refreshed weekly. Keyless.

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

```json
"mcpServers": {
  "msha-mines": {
    "command": "npx",
    "args": ["-y","@pipeworx/mcp-msha-mines"]
  }
}
```

## Documentation

## What Msha Mines does

Msha Mines exposes selected US Mine Safety and Health Administration records through MCP. It helps an agent identify mines by operator, controller, or mine name, then inspect a mine's identifying information and recent activity using its MSHA Mine ID.

Search results can include the mine ID, operating status, mine type, coal or metal/non-metal classification, commodity, state, and current operator or controller. Detail results add recent inspections, violations with assessed penalties, significant-and-substantial status, abatement or termination dates, and quarterly employment and coal production summed across subunits.

The package is an independent integration and is not affiliated with MSHA. Its records come from MSHA's public-domain Open Government Data portal.

## How it works

The service uses four MSHA bulk datasets: the master mine list, violations, inspections, and quarterly employment and production. A scheduled ingestion process loads these files into a Supabase mirror, replacing the tables as a complete weekly snapshot. Successful responses report `data_as_of`, taken from the backing data's load timestamp.

The hosted MCP endpoint is available at `https://gateway.pipeworx.io/msha-mines/mcp`. A local npm package provides a stdio bridge that forwards MCP calls to that endpoint; it does not provide offline operation. The same gateway also exposes HTTP tool calls for clients or scripts that do not use MCP.

## Setup and configuration

Add the hosted endpoint to an MCP client:

```json
{
  "mcpServers": {
    "msha-mines": {
      "url": "https://gateway.pipeworx.io/msha-mines/mcp"
    }
  }
}
```

The endpoint is keyless. Claude Desktop, Cursor, Windsurf, and other MCP clients can connect directly. Alternatively, configure the local bridge with `npx`:

```json
{
  "mcpServers": {
    "msha-mines": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-msha-mines"]
    }
  }
}
```

The npm bridge requires network access. Anonymous use is capped at 50 calls per day; a free account increases the limit to 200 calls per day.

## Tools and capabilities

- `msha_mine_search(query, state?, status?, limit?)` searches by operator, controller, or mine name and returns matching mine records.
- `msha_mine_detail(mine_id, violations_limit?, inspections_limit?)` retrieves current mine attributes, recent inspections and violations, and recent quarterly employment and coal production.
- `msha_violation_counts(mine_id?, mine_name?, year?, year_from?, year_to?)` counts violations by calendar year or range, including issuer category and S&S status.

Use the search tool to find a Mine ID before calling the detail tool. The violation-count tool can also resolve a mine or operator/controller name when it identifies exactly one mine; ambiguous and unmatched names return a named error with candidates where applicable. Detail violation results accept a maximum `violations_limit` of 100.

## Limitations and notes

The violations, inspections, and employment/production tables retain only the most recent five calendar years. This window moves forward during refreshes. Responses that use these bounded tables include a `bound` field, and violation-count requests outside the loaded window identify that coverage rather than returning a misleading zero.

The full mine master list is retained, including mines that have ever received an MSHA Mine ID. A missing known ID returns `found: false` with `data_as_of`. If a refresh has never successfully populated the tables, queries return a dataset-unavailable error instead of treating every mine as absent.

Pack endpoints also list shared Pipeworx gateway meta-tools in addition to the mine-specific tools. The full gateway endpoint exposes the broader catalog, while `ask_pipeworx` can route questions beyond this pack from either gateway connection.

_Full upstream README: https://allmcps.com/mcp/msha-mines/readme_