Content
# kosha-mcp
An MCP server that wraps the public OpenAPI services of the **Korea Occupational
Safety and Health Agency (KOSHA)**, served through Korea's national open-data
portal (`data.go.kr` / `apis.data.go.kr`).
## Tool List
| Tool | Description | Type |
|------|-------------|------|
| `kosha_search_accident_cases` | Search domestic accident cases by keyword and industry (construction, manufacturing, etc.) | read-only |
| `kosha_api_request` | A general-purpose tool for calling arbitrary KOSHA data.go.kr endpoints with authentication (MSDS, KOSHA GUIDE, etc.) | read-only |
`kosha_api_request` is an escape route for services that don't have a dedicated tool yet (Material Safety Data Sheets MSDS, KOSHA GUIDE lists, educational video recommendations, etc.), allowing you to call them directly with just the `path` and `params`.
## Prerequisites: Service Key Issuance
1. [Sign up/login to the Public Data Portal](https://www.data.go.kr)
2. Search for the desired KOSHA service and click **"Apply for Use"**
- [Domestic Accident Cases Board Inquiry](https://www.data.go.kr/data/15121001/openapi.do)
- [Material Safety Data Sheets (MSDS)](https://www.data.go.kr/data/15001197/openapi.do)
- [KOSHA GUIDE List](https://www.data.go.kr/data/15116595/fileData.do)
3. Copy the **Decoding** authentication key from your My Page → use as `KOSHA_SERVICE_KEY`
4. Check the exact **request URL (path)** for each service in their **"Open API Usage Guide"** documents
(paths vary by service; specify as environment variables if needed)
> Approval for usage application usually takes tens of minutes to an hour, and data can be queried only after approval.
## Installation
```bash
# Using uv (recommended)
uv sync
# or using pip
pip install -e .
```
## Environment Variables
| Variable | Required | Default Value | Description |
|------|----------|---------------|--------------|
| `KOSHA_SERVICE_KEY` | ✅ | – | data.go.kr **Decoding** authentication key |
| `KOSHA_API_BASE` | – | `https://apis.data.go.kr` | KOSHA service base host |
| `KOSHA_ACCIDENT_PATH` | – | `/B552468/dscasBrd/getDscasBrdList` | Accident cases service path (replace with usage guide value) |
Copy `.env.example` and fill in the values. `.env` will not be committed.
```bash
cp .env.example .env
```
## Running / Testing
```bash
# Run directly (stdio)
KOSHA_SERVICE_KEY=issued_key python -m kosha_mcp.server
# Inspect with MCP Inspector
npx @modelcontextprotocol/inspector uv run kosha-mcp
```
## Registering with Claude Desktop / Claude Code
Add to `claude_desktop_config.json` (or MCP settings):
```json
{
"mcpServers": {
"kosha": {
"command": "uv",
"args": ["--directory", "/absolute/path/kosha-mcp", "run", "kosha-mcp"],
"env": {
"KOSHA_SERVICE_KEY": "issued_Decoding_key"
}
}
}
}
```
## Usage Examples
- "Find 5 construction accident cases"
→ `kosha_search_accident_cases(keyword="fall", business="construction", num_of_rows=5)`
- "Search for Toluene MSDS" (check the path in the service usage guide)
→ `kosha_api_request(path="/<msds-service-path>", params={"searchWrd": "Toluene"})`
## Notes
- Exact **service paths and parameter names are defined in each service's data.go.kr usage guide**. If you get a 404, check the path.
- This project is not an official product of KOSHA or the Public Data Portal but an unofficial community tool wrapping public OpenAPI services.
## License
MIT
