Msha Mines

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:

{
  "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:

{
  "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.