内容
# kosha-mcp
韩国产业安全卫生공단（KOSHA）公开的OpenAPI服务，通过韩国国家开放数据门户（data.go.kr）提供，现已封装成 **MCP服务器**，可供Claude等MCP客户端作为工具使用。
韩国产业安全卫生공단（KOSHA）公开的OpenAPI服务，通过韩国国家开放数据门户（data.go.kr）提供，现已封装成 **MCP服务器**，可供Claude等MCP客户端作为工具使用。
## 提供工具
| 工具 | 说明 | 类型 |
|------|------|------|
| `kosha_search_accident_cases` | 搜索国内事故案例板块，可按关键词、行业（建筑/制造等）搜索 | 只读 |
| `kosha_api_request` | 调用任意KOSHA data.go.kr端点并进行认证的通用工具（MSDS、KOSHA GUIDE等） | 只读 |
`kosha_api_request`是一个通用的工具，可以用于调用尚未有专用工具的服务，如物质安全卫生资料（MSDS）、KOSHA GUIDE列表、教育视频推荐等，只需提供`path`和`params`即可。
## 准备工作：获取服务密钥
1. [公共数据门户](https://www.data.go.kr) 注册/登录
2. 搜索所需的KOSHA服务并提交**"应用申请"**
- [国内事故案例板块查询](https://www.data.go.kr/data/15121001/openapi.do)
- [物质安全卫生资料（MSDS）](https://www.data.go.kr/data/15001197/openapi.do)
- [KOSHA GUIDE列表](https://www.data.go.kr/data/15116595/fileData.do)
3. 在个人页面复制**一般认证密钥（解码）**的值，并将其用作`KOSHA_SERVICE_KEY`
4. 在每个服务的**"开放API使用指南"**文档中查找准确的**请求URL（路径）**
（路径因服务而异，如有需要，可在以下环境变量中指定）
> 应用申请的批准通常需要几十分钟到1小时，批准后方可查询数据。
## 安装
```bash
# 使用uv（推荐）
uv sync
# 或使用pip
pip install -e .
```
## 环境变量
| 变量 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| `KOSHA_SERVICE_KEY` | ✅ | – | data.go.kr **解码**认证密钥 |
| `KOSHA_API_BASE` | – | `https://apis.data.go.kr` | KOSHA服务基准主机 |
| `KOSHA_ACCIDENT_PATH` | – | `/B552468/dscasBrd/getDscasBrdList` | 事故案例服务路径（替换为使用指南的值） |
复制`.env.example`并填写。`.env`不会被提交。
```bash
cp .env.example .env
```
## 运行/测试
```bash
# 直接运行（stdio）
KOSHA_SERVICE_KEY= 발급받은키 python -m kosha_mcp.server
# 使用MCP Inspector检查
npx @modelcontextprotocol/inspector uv run kosha-mcp
```
## 注册到Claude Desktop/Claude Code
在`claude_desktop_config.json`（或MCP设置）中添加：
```json
{
"mcpServers": {
"kosha": {
"command": "uv",
"args": ["--directory", "/绝对/路径/kosha-mcp", "run", "kosha-mcp"],
"env": {
"KOSHA_SERVICE_KEY": " 발급받은_Decoding_키"
}
}
}
}
```
## 使用示例
- "找出5个建筑业的坠落事故案例"
→ `kosha_search_accident_cases(keyword="坠落", business="construction", num_of_rows=5)`
- "搜索甲苯MSDS"（路径请参考该服务的开放API使用指南）
→ `kosha_api_request(path="/<msds-service-path>", params={"searchWrd": "甲苯"})`
## 注意事项
- 准确的**服务路径和参数名称在各服务的data.go.kr使用指南**中定义。如果出现404错误，请从路径开始检查。
- 本项目不是KOSHA/公共数据门户的官方产品，而是基于公开的OpenAPI封装的非官方社区工具。
## License
MIT
