# NPS Business Enrollment MCP Server
국민연금공단 사업장 가입 내역 조회를 위한 MCP 서버입니다.
## 개요
이 MCP 서버는 [data.go.kr](https://www.data.go.kr)에서 제공하는 국민연금공단 사업장 가입 내역 API를 Model Context Protocol(MCP)로 래핑하여, AI 도구들이 쉽게 국민연금 사업장 정보를 조회할 수 있도록 합니다.
## 설치
### pip을 사용한 설치
```bash
pip install data-go-mcp.nps-business-enrollment
```
### UV를 사용한 설치
```bash
uv pip install data-go-mcp.nps-business-enrollment
```
## 환경 변수 설정
이 서버를 사용하려면 data.go.kr에서 발급받은 API 키가 필요합니다:
```bash
export NPS_API_KEY="your-api-key-here"
```
API 키는 [data.go.kr](https://www.data.go.kr)에서 회원가입 후 "국민연금공단_국민연금 가입 사업장 내역" API를 신청하여 발급받을 수 있습니다.
## 사용 가능한 도구
### search_business
국민연금에 가입된 사업장 정보를 검색합니다.
**파라미터:**
- `ldong_addr_mgpl_dg_cd` (선택): 법정동주소 광역시도 코드 (2자리)
- 예: "11" (서울특별시), "26" (부산광역시)
- `ldong_addr_mgpl_sggu_cd` (선택): 법정동주소 시군구 코드 (5자리)
- 예: "11680" (서울특별시 강남구)
- `ldong_addr_mgpl_sggu_emd_cd` (선택): 법정동주소 읍면동 코드 (8자리)
- 예: "11680600" (서울특별시 강남구 논현동)
- `wkpl_nm` (선택): 사업장명
- 예: "삼성전자", "국민은행"
- `bzowr_rgst_no` (선택): 사업자등록번호 (앞 6자리)
- 예: "124815" (삼성전자 앞 6자리)
- `page_no`: 페이지 번호 (기본값: 1)
- `num_of_rows`: 한 페이지 결과 수 (기본값: 100, 최대: 100)
**반환값:**
- `items`: 사업장 정보 리스트
- 각 항목에는 사업장명, 주소, 가입자수, 업종 등의 정보 포함
- `page_no`: 현재 페이지 번호
- `num_of_rows`: 페이지당 결과 수
- `total_count`: 전체 결과 수
## Claude Desktop 설정
Claude Desktop에서 이 서버를 사용하려면 설정 파일을 수정하세요:
**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"data-go-mcp.nps-business-enrollment": {
"command": "uvx",
"args": ["data-go-mcp.nps-business-enrollment"],
"env": {
"NPS_API_KEY": "your-api-key-here"
}
}
}
}
```
## Cline 설정
VS Code의 Cline 확장에서 사용하려면:
`.vscode/cline_mcp_settings.json`:
```json
{
"mcpServers": {
"data-go-mcp.nps-business-enrollment": {
"command": "python",
"args": ["-m", "data_go_mcp.nps_business_enrollment.server"],
"env": {
"NPS_API_KEY": "your-api-key-here"
}
}
}
}
```
## 사용 예시
AI 도구에서 다음과 같은 프롬프트를 사용할 수 있습니다:
### 지역별 사업장 검색
```
"서울특별시에 있는 사업장을 검색해줘"
"강남구에 있는 사업장 목록을 보여줘"
"서울시 강남구 논현동의 사업장을 찾아줘"
```
### 사업장명으로 검색
```
"삼성전자 사업장 정보를 찾아줘"
"국민은행이라는 이름이 포함된 사업장을 검색해줘"
```
### 사업자등록번호로 검색
```
"사업자등록번호 124815로 시작하는 사업장을 조회해줘"
```
### 복합 검색
```
"서울시 강남구에 있는 삼성 관련 사업장을 찾아줘"
"부산에 있는 제조업 사업장을 검색해줘"
```
## 법정동 코드 참조
법정동 코드는 [행정표준코드관리시스템](https://www.code.go.kr)에서 확인할 수 있습니다.
주요 광역시도 코드:
- 11: 서울특별시
- 26: 부산광역시
- 27: 대구광역시
- 28: 인천광역시
- 29: 광주광역시
- 30: 대전광역시
- 31: 울산광역시
- 41: 경기도
- 42: 강원도
- 43: 충청북도
- 44: 충청남도
- 45: 전라북도
- 46: 전라남도
- 47: 경상북도
- 48: 경상남도
- 50: 제주특별자치도
## 개발
### 소스에서 실행
```bash
# 저장소 클론
git clone https://github.com/yourusername/data-go-mcp-servers.git
cd data-go-mcp-servers/src/nps-business-enrollment
# 의존성 설치
uv sync
# 서버 실행
uv run python -m data_go_mcp.nps_business_enrollment.server
```
### 테스트 실행
```bash
uv run pytest tests/
```
## 문제 해결
### API 키 오류
- API 키가 올바르게 설정되었는지 확인하세요
- API 키가 활성화되어 있는지 data.go.kr에서 확인하세요
- 일일 호출 한도를 초과하지 않았는지 확인하세요
### 검색 결과가 없음
- 법정동 코드가 올바른지 확인하세요
- 사업장명이나 사업자등록번호가 정확한지 확인하세요
- 검색 조건을 완화해보세요 (예: 시군구 단위로만 검색)
## 라이센스
Apache License 2.0 - 자세한 내용은 [LICENSE](../../LICENSE) 파일을 참조하세요.
## 관련 링크
- [국민연금공단 오픈API](https://www.data.go.kr/data/15084277/openapi.do)
- [법정동코드 조회](https://www.code.go.kr)
- [MCP 프로토콜 문서](https://modelcontextprotocol.io)
Raw data
{
"_id": null,
"home_page": null,
"name": "data-go-mcp.nps-business-enrollment",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, business, data.go.kr, enrollment, korea, mcp, nps, pension",
"author": "Data.go.kr MCP Servers Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/33/26/65f2e168d4c179e4910bdfd6b721119b376e9962f7ac6b295e1e38046405/data_go_mcp_nps_business_enrollment-0.1.0.tar.gz",
"platform": null,
"description": "# NPS Business Enrollment MCP Server\n\n\uad6d\ubbfc\uc5f0\uae08\uacf5\ub2e8 \uc0ac\uc5c5\uc7a5 \uac00\uc785 \ub0b4\uc5ed \uc870\ud68c\ub97c \uc704\ud55c MCP \uc11c\ubc84\uc785\ub2c8\ub2e4.\n\n## \uac1c\uc694\n\n\uc774 MCP \uc11c\ubc84\ub294 [data.go.kr](https://www.data.go.kr)\uc5d0\uc11c \uc81c\uacf5\ud558\ub294 \uad6d\ubbfc\uc5f0\uae08\uacf5\ub2e8 \uc0ac\uc5c5\uc7a5 \uac00\uc785 \ub0b4\uc5ed API\ub97c Model Context Protocol(MCP)\ub85c \ub798\ud551\ud558\uc5ec, AI \ub3c4\uad6c\ub4e4\uc774 \uc27d\uac8c \uad6d\ubbfc\uc5f0\uae08 \uc0ac\uc5c5\uc7a5 \uc815\ubcf4\ub97c \uc870\ud68c\ud560 \uc218 \uc788\ub3c4\ub85d \ud569\ub2c8\ub2e4.\n\n## \uc124\uce58\n\n### pip\uc744 \uc0ac\uc6a9\ud55c \uc124\uce58\n\n```bash\npip install data-go-mcp.nps-business-enrollment\n```\n\n### UV\ub97c \uc0ac\uc6a9\ud55c \uc124\uce58\n\n```bash\nuv pip install data-go-mcp.nps-business-enrollment\n```\n\n## \ud658\uacbd \ubcc0\uc218 \uc124\uc815\n\n\uc774 \uc11c\ubc84\ub97c \uc0ac\uc6a9\ud558\ub824\uba74 data.go.kr\uc5d0\uc11c \ubc1c\uae09\ubc1b\uc740 API \ud0a4\uac00 \ud544\uc694\ud569\ub2c8\ub2e4:\n\n```bash\nexport NPS_API_KEY=\"your-api-key-here\"\n```\n\nAPI \ud0a4\ub294 [data.go.kr](https://www.data.go.kr)\uc5d0\uc11c \ud68c\uc6d0\uac00\uc785 \ud6c4 \"\uad6d\ubbfc\uc5f0\uae08\uacf5\ub2e8_\uad6d\ubbfc\uc5f0\uae08 \uac00\uc785 \uc0ac\uc5c5\uc7a5 \ub0b4\uc5ed\" API\ub97c \uc2e0\uccad\ud558\uc5ec \ubc1c\uae09\ubc1b\uc744 \uc218 \uc788\uc2b5\ub2c8\ub2e4.\n\n## \uc0ac\uc6a9 \uac00\ub2a5\ud55c \ub3c4\uad6c\n\n### search_business\n\n\uad6d\ubbfc\uc5f0\uae08\uc5d0 \uac00\uc785\ub41c \uc0ac\uc5c5\uc7a5 \uc815\ubcf4\ub97c \uac80\uc0c9\ud569\ub2c8\ub2e4.\n\n**\ud30c\ub77c\ubbf8\ud130:**\n- `ldong_addr_mgpl_dg_cd` (\uc120\ud0dd): \ubc95\uc815\ub3d9\uc8fc\uc18c \uad11\uc5ed\uc2dc\ub3c4 \ucf54\ub4dc (2\uc790\ub9ac)\n - \uc608: \"11\" (\uc11c\uc6b8\ud2b9\ubcc4\uc2dc), \"26\" (\ubd80\uc0b0\uad11\uc5ed\uc2dc)\n- `ldong_addr_mgpl_sggu_cd` (\uc120\ud0dd): \ubc95\uc815\ub3d9\uc8fc\uc18c \uc2dc\uad70\uad6c \ucf54\ub4dc (5\uc790\ub9ac)\n - \uc608: \"11680\" (\uc11c\uc6b8\ud2b9\ubcc4\uc2dc \uac15\ub0a8\uad6c)\n- `ldong_addr_mgpl_sggu_emd_cd` (\uc120\ud0dd): \ubc95\uc815\ub3d9\uc8fc\uc18c \uc74d\uba74\ub3d9 \ucf54\ub4dc (8\uc790\ub9ac)\n - \uc608: \"11680600\" (\uc11c\uc6b8\ud2b9\ubcc4\uc2dc \uac15\ub0a8\uad6c \ub17c\ud604\ub3d9)\n- `wkpl_nm` (\uc120\ud0dd): \uc0ac\uc5c5\uc7a5\uba85\n - \uc608: \"\uc0bc\uc131\uc804\uc790\", \"\uad6d\ubbfc\uc740\ud589\"\n- `bzowr_rgst_no` (\uc120\ud0dd): \uc0ac\uc5c5\uc790\ub4f1\ub85d\ubc88\ud638 (\uc55e 6\uc790\ub9ac)\n - \uc608: \"124815\" (\uc0bc\uc131\uc804\uc790 \uc55e 6\uc790\ub9ac)\n- `page_no`: \ud398\uc774\uc9c0 \ubc88\ud638 (\uae30\ubcf8\uac12: 1)\n- `num_of_rows`: \ud55c \ud398\uc774\uc9c0 \uacb0\uacfc \uc218 (\uae30\ubcf8\uac12: 100, \ucd5c\ub300: 100)\n\n**\ubc18\ud658\uac12:**\n- `items`: \uc0ac\uc5c5\uc7a5 \uc815\ubcf4 \ub9ac\uc2a4\ud2b8\n - \uac01 \ud56d\ubaa9\uc5d0\ub294 \uc0ac\uc5c5\uc7a5\uba85, \uc8fc\uc18c, \uac00\uc785\uc790\uc218, \uc5c5\uc885 \ub4f1\uc758 \uc815\ubcf4 \ud3ec\ud568\n- `page_no`: \ud604\uc7ac \ud398\uc774\uc9c0 \ubc88\ud638\n- `num_of_rows`: \ud398\uc774\uc9c0\ub2f9 \uacb0\uacfc \uc218\n- `total_count`: \uc804\uccb4 \uacb0\uacfc \uc218\n\n## Claude Desktop \uc124\uc815\n\nClaude Desktop\uc5d0\uc11c \uc774 \uc11c\ubc84\ub97c \uc0ac\uc6a9\ud558\ub824\uba74 \uc124\uc815 \ud30c\uc77c\uc744 \uc218\uc815\ud558\uc138\uc694:\n\n**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"data-go-mcp.nps-business-enrollment\": {\n \"command\": \"uvx\",\n \"args\": [\"data-go-mcp.nps-business-enrollment\"],\n \"env\": {\n \"NPS_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n## Cline \uc124\uc815\n\nVS Code\uc758 Cline \ud655\uc7a5\uc5d0\uc11c \uc0ac\uc6a9\ud558\ub824\uba74:\n\n`.vscode/cline_mcp_settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"data-go-mcp.nps-business-enrollment\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"data_go_mcp.nps_business_enrollment.server\"],\n \"env\": {\n \"NPS_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n## \uc0ac\uc6a9 \uc608\uc2dc\n\nAI \ub3c4\uad6c\uc5d0\uc11c \ub2e4\uc74c\uacfc \uac19\uc740 \ud504\ub86c\ud504\ud2b8\ub97c \uc0ac\uc6a9\ud560 \uc218 \uc788\uc2b5\ub2c8\ub2e4:\n\n### \uc9c0\uc5ed\ubcc4 \uc0ac\uc5c5\uc7a5 \uac80\uc0c9\n```\n\"\uc11c\uc6b8\ud2b9\ubcc4\uc2dc\uc5d0 \uc788\ub294 \uc0ac\uc5c5\uc7a5\uc744 \uac80\uc0c9\ud574\uc918\"\n\"\uac15\ub0a8\uad6c\uc5d0 \uc788\ub294 \uc0ac\uc5c5\uc7a5 \ubaa9\ub85d\uc744 \ubcf4\uc5ec\uc918\"\n\"\uc11c\uc6b8\uc2dc \uac15\ub0a8\uad6c \ub17c\ud604\ub3d9\uc758 \uc0ac\uc5c5\uc7a5\uc744 \ucc3e\uc544\uc918\"\n```\n\n### \uc0ac\uc5c5\uc7a5\uba85\uc73c\ub85c \uac80\uc0c9\n```\n\"\uc0bc\uc131\uc804\uc790 \uc0ac\uc5c5\uc7a5 \uc815\ubcf4\ub97c \ucc3e\uc544\uc918\"\n\"\uad6d\ubbfc\uc740\ud589\uc774\ub77c\ub294 \uc774\ub984\uc774 \ud3ec\ud568\ub41c \uc0ac\uc5c5\uc7a5\uc744 \uac80\uc0c9\ud574\uc918\"\n```\n\n### \uc0ac\uc5c5\uc790\ub4f1\ub85d\ubc88\ud638\ub85c \uac80\uc0c9\n```\n\"\uc0ac\uc5c5\uc790\ub4f1\ub85d\ubc88\ud638 124815\ub85c \uc2dc\uc791\ud558\ub294 \uc0ac\uc5c5\uc7a5\uc744 \uc870\ud68c\ud574\uc918\"\n```\n\n### \ubcf5\ud569 \uac80\uc0c9\n```\n\"\uc11c\uc6b8\uc2dc \uac15\ub0a8\uad6c\uc5d0 \uc788\ub294 \uc0bc\uc131 \uad00\ub828 \uc0ac\uc5c5\uc7a5\uc744 \ucc3e\uc544\uc918\"\n\"\ubd80\uc0b0\uc5d0 \uc788\ub294 \uc81c\uc870\uc5c5 \uc0ac\uc5c5\uc7a5\uc744 \uac80\uc0c9\ud574\uc918\"\n```\n\n## \ubc95\uc815\ub3d9 \ucf54\ub4dc \ucc38\uc870\n\n\ubc95\uc815\ub3d9 \ucf54\ub4dc\ub294 [\ud589\uc815\ud45c\uc900\ucf54\ub4dc\uad00\ub9ac\uc2dc\uc2a4\ud15c](https://www.code.go.kr)\uc5d0\uc11c \ud655\uc778\ud560 \uc218 \uc788\uc2b5\ub2c8\ub2e4.\n\n\uc8fc\uc694 \uad11\uc5ed\uc2dc\ub3c4 \ucf54\ub4dc:\n- 11: \uc11c\uc6b8\ud2b9\ubcc4\uc2dc\n- 26: \ubd80\uc0b0\uad11\uc5ed\uc2dc\n- 27: \ub300\uad6c\uad11\uc5ed\uc2dc\n- 28: \uc778\ucc9c\uad11\uc5ed\uc2dc\n- 29: \uad11\uc8fc\uad11\uc5ed\uc2dc\n- 30: \ub300\uc804\uad11\uc5ed\uc2dc\n- 31: \uc6b8\uc0b0\uad11\uc5ed\uc2dc\n- 41: \uacbd\uae30\ub3c4\n- 42: \uac15\uc6d0\ub3c4\n- 43: \ucda9\uccad\ubd81\ub3c4\n- 44: \ucda9\uccad\ub0a8\ub3c4\n- 45: \uc804\ub77c\ubd81\ub3c4\n- 46: \uc804\ub77c\ub0a8\ub3c4\n- 47: \uacbd\uc0c1\ubd81\ub3c4\n- 48: \uacbd\uc0c1\ub0a8\ub3c4\n- 50: \uc81c\uc8fc\ud2b9\ubcc4\uc790\uce58\ub3c4\n\n## \uac1c\ubc1c\n\n### \uc18c\uc2a4\uc5d0\uc11c \uc2e4\ud589\n\n```bash\n# \uc800\uc7a5\uc18c \ud074\ub860\ngit clone https://github.com/yourusername/data-go-mcp-servers.git\ncd data-go-mcp-servers/src/nps-business-enrollment\n\n# \uc758\uc874\uc131 \uc124\uce58\nuv sync\n\n# \uc11c\ubc84 \uc2e4\ud589\nuv run python -m data_go_mcp.nps_business_enrollment.server\n```\n\n### \ud14c\uc2a4\ud2b8 \uc2e4\ud589\n\n```bash\nuv run pytest tests/\n```\n\n## \ubb38\uc81c \ud574\uacb0\n\n### API \ud0a4 \uc624\ub958\n- API \ud0a4\uac00 \uc62c\ubc14\ub974\uac8c \uc124\uc815\ub418\uc5c8\ub294\uc9c0 \ud655\uc778\ud558\uc138\uc694\n- API \ud0a4\uac00 \ud65c\uc131\ud654\ub418\uc5b4 \uc788\ub294\uc9c0 data.go.kr\uc5d0\uc11c \ud655\uc778\ud558\uc138\uc694\n- \uc77c\uc77c \ud638\ucd9c \ud55c\ub3c4\ub97c \ucd08\uacfc\ud558\uc9c0 \uc54a\uc558\ub294\uc9c0 \ud655\uc778\ud558\uc138\uc694\n\n### \uac80\uc0c9 \uacb0\uacfc\uac00 \uc5c6\uc74c\n- \ubc95\uc815\ub3d9 \ucf54\ub4dc\uac00 \uc62c\ubc14\ub978\uc9c0 \ud655\uc778\ud558\uc138\uc694\n- \uc0ac\uc5c5\uc7a5\uba85\uc774\ub098 \uc0ac\uc5c5\uc790\ub4f1\ub85d\ubc88\ud638\uac00 \uc815\ud655\ud55c\uc9c0 \ud655\uc778\ud558\uc138\uc694\n- \uac80\uc0c9 \uc870\uac74\uc744 \uc644\ud654\ud574\ubcf4\uc138\uc694 (\uc608: \uc2dc\uad70\uad6c \ub2e8\uc704\ub85c\ub9cc \uac80\uc0c9)\n\n## \ub77c\uc774\uc13c\uc2a4\n\nApache License 2.0 - \uc790\uc138\ud55c \ub0b4\uc6a9\uc740 [LICENSE](../../LICENSE) \ud30c\uc77c\uc744 \ucc38\uc870\ud558\uc138\uc694.\n\n## \uad00\ub828 \ub9c1\ud06c\n\n- [\uad6d\ubbfc\uc5f0\uae08\uacf5\ub2e8 \uc624\ud508API](https://www.data.go.kr/data/15084277/openapi.do)\n- [\ubc95\uc815\ub3d9\ucf54\ub4dc \uc870\ud68c](https://www.code.go.kr)\n- [MCP \ud504\ub85c\ud1a0\ucf5c \ubb38\uc11c](https://modelcontextprotocol.io)",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "MCP server for Korea National Pension Service business enrollment API from data.go.kr",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/yourusername/data-go-mcp-servers/issues",
"Changelog": "https://github.com/yourusername/data-go-mcp-servers/blob/main/src/nps-business-enrollment/CHANGELOG.md",
"Documentation": "https://github.com/yourusername/data-go-mcp-servers/tree/main/src/nps-business-enrollment",
"Homepage": "https://github.com/yourusername/data-go-mcp-servers",
"Repository": "https://github.com/yourusername/data-go-mcp-servers"
},
"split_keywords": [
"api",
" business",
" data.go.kr",
" enrollment",
" korea",
" mcp",
" nps",
" pension"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3807cc9a04d917a6f23ec2a320881f0f6bc84ac3041406a0cdf5e1ef7887aa6a",
"md5": "eb1939dd9120a1bb4f869432c7e7dc23",
"sha256": "6cb68aedf35465807cdaa008bf0ca1b5ad4ad03044d3c03f5b0d7f14e542a3f0"
},
"downloads": -1,
"filename": "data_go_mcp_nps_business_enrollment-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb1939dd9120a1bb4f869432c7e7dc23",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10539,
"upload_time": "2025-08-28T07:30:07",
"upload_time_iso_8601": "2025-08-28T07:30:07.581009Z",
"url": "https://files.pythonhosted.org/packages/38/07/cc9a04d917a6f23ec2a320881f0f6bc84ac3041406a0cdf5e1ef7887aa6a/data_go_mcp_nps_business_enrollment-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "332665f2e168d4c179e4910bdfd6b721119b376e9962f7ac6b295e1e38046405",
"md5": "fcd36e730527be590db973b75834c4cc",
"sha256": "1c3a66b59201a32fa99b78cbff332712870972a45cebc3529e6323cd161bb53c"
},
"downloads": -1,
"filename": "data_go_mcp_nps_business_enrollment-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "fcd36e730527be590db973b75834c4cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 10019,
"upload_time": "2025-08-28T07:30:09",
"upload_time_iso_8601": "2025-08-28T07:30:09.048898Z",
"url": "https://files.pythonhosted.org/packages/33/26/65f2e168d4c179e4910bdfd6b721119b376e9962f7ac6b295e1e38046405/data_go_mcp_nps_business_enrollment-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 07:30:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "data-go-mcp-servers",
"github_not_found": true,
"lcname": "data-go-mcp.nps-business-enrollment"
}
JSON
