# MCP NPS Business Enrollment Server
국민연금 가입 사업장 내역 API를 MCP(Model Context Protocol) 서버로 제공하는 Python 패키지입니다.
## 주요 기능
**기업 임직원 수 및 예상 평균 월급 조회**
- 국민연금 가입자 수로 실제 임직원 규모 파악
- 당월 고지금액 기반 예상 평균 월급 계산 (추정값)
- 월별 입사/퇴사 현황 추적
## 작동 원리
```mermaid
graph LR
A[Claude/MCP Client] --> B[MCP Server]
B --> C[국민연금공단 API]
C --> D[사업장 정보]
D --> B
B --> E[데이터 처리<br/>평균 월급 계산]
E --> A
```
1. **MCP 클라이언트** (Claude Desktop/Code)가 사용자 요청을 받음
2. **MCP 서버**가 국민연금공단 OpenAPI를 호출
3. 반환된 데이터에서 가입자수, 당월고지금액 추출
4. 예상 평균 월급 계산: `당월고지금액 ÷ 가입자수 ÷ 0.09 (보험료율)`
5. 결과를 사용자에게 반환
## 개요
이 프로젝트는 공공데이터포털에서 제공하는 [국민연금공단의 사업장 정보조회 서비스](https://www.data.go.kr/data/3046071/openapi.do)를 MCP 서버로 구현한 것입니다. Claude Desktop 및 기타 MCP 호환 클라이언트에서 국민연금 가입 사업장 정보를 쉽게 조회할 수 있습니다.
## MCP Tools
1. **search_business**
- 사업장 정보 조회
- 지역별, 사업장명, 사업자등록번호로 검색
- 페이지네이션 지원
2. **get_business_detail**
- 사업장 상세정보 조회
- 업종코드, 가입자수, 당월고지금액 등 상세정보
3. **get_period_status**
- 기간별 현황 정보 조회
- 월별 취득자/상실자 현황
## MCP 클라이언트에 빠른 설치
### 테스트용 API 키
다음 테스트용 API 키를 제공합니다. 아래 설치 명령어에서 바로 사용할 수 있습니다:
```
cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==
```
⚠️ **중요 안내**:
- 이 테스트용 API 키는 **하루 총 10,000건**까지만 호출 가능합니다
- 여러 사용자가 공유하므로 **언제든지 호출이 실패할 수 있습니다**
- 안정적인 사용을 위해서는 [개인 API 키 발급](#1-api-키-발급)을 권장합니다
### Claude Desktop
**가장 간단한 방법 - PyPI 패키지 사용:**
1. Claude Desktop 설정 파일 열기:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. 다음 설정 추가 (테스트용 API 키 포함):
```json
{
"mcpServers": {
"nps-business": {
"command": "uvx",
"args": ["mcp-nps-business-enrollment"],
"env": {
"API_KEY": "cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw=="
}
}
}
}
```
3. Claude Desktop 재시작
### Claude Code
```bash
# 테스트용 API 키로 설치
claude mcp add nps-business \
--env API_KEY="cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==" \
-- uvx mcp-nps-business-enrollment
```
### Codex CLI
Codex CLI에서 MCP 서버를 사용하려면 `~/.codex/config.toml` 파일을 수정합니다:
1. Codex CLI 설치 (필요한 경우):
```bash
npm install -g @openai/codex
```
2. 설정 파일 편집 `~/.codex/config.toml`:
```toml
# NPS Business Enrollment MCP Server 설정
[mcp_servers.nps-business]
command = "uvx"
args = ["mcp-nps-business-enrollment"]
env = { API_KEY = "cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==" }
```
3. Codex 실행:
```bash
codex # 프로젝트 디렉토리에서 실행
```
## 개발자용 설치
### 로컬 개발 환경에서 MCP 클라이언트에 설치
이 레포지토리를 클론하여 로컬 개발 버전을 MCP 클라이언트에 직접 연결할 수 있습니다.
#### 1. 레포지토리 클론 및 설정
```bash
# 레포지토리 클론
git clone https://github.com/Koomook/mcp_NPS_BusinessEnrollment.git
cd mcp_NPS_BusinessEnrollment
# uv를 사용한 의존성 설치
uv sync
```
#### 2. Claude Desktop에 로컬 개발 버전 연결
Claude Desktop 설정 파일을 열어 다음과 같이 설정합니다:
```json
{
"mcpServers": {
"nps-business-dev": {
"command": "uv",
"args": ["run", "mcp-nps-business-enrollment"],
"cwd": "/path/to/mcp_NPS_BusinessEnrollment",
"env": {
"API_KEY": "cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw=="
}
}
}
}
```
**참고:** `cwd`를 실제 클론한 디렉토리 경로로 변경하세요.
#### 3. Claude Code에 로컬 개발 버전 연결
```bash
# 클론한 디렉토리에서 실행
claude mcp add nps-business-dev \
--env API_KEY="cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==" \
-- uv run --directory /path/to/mcp_NPS_BusinessEnrollment mcp-nps-business-enrollment
```
### PyPI 패키지로 개발
```bash
# PyPI에서 설치
pip install mcp-nps-business-enrollment
# 또는 uv 사용 (권장)
uv pip install mcp-nps-business-enrollment
```
## 환경 설정
### 1. API 키 발급
공공데이터포털에서 제공하는 [국민연금공단의 사업장 정보조회 서비스](https://www.data.go.kr/data/3046071/openapi.do)에서 "국민연금 가입 사업장 내역" API 활용 신청 후 인증키를 발급받습니다.
### 2. 환경변수 설정 (개발용)
개발 환경에서 테스트할 때는 `.env` 파일을 생성하고 다음 내용을 입력합니다:
```env
# API 키 (필수)
API_KEY="your_api_key_here"
# 테스트용 API 키 예시:
# API_KEY="cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw=="
```
**참고:** API endpoint는 자동으로 설정되므로 별도 설정이 필요 없습니다.
## 사용 예시
### MCP Client(Claude Desktop 등)에서 사용
```
임직원 수 및 평균 월급 조회:
"스페이스와이" 회사의 임직원 수와 예상 평균 월급을 알려줘
사업장명으로 검색:
"삼성전자"라는 이름이 포함된 사업장을 검색해줘
지역별 검색:
서울특별시 강남구에 있는 사업장들을 찾아줘
상세정보 조회:
식별번호 12345인 사업장의 상세정보를 보여줘
기간별 현황:
식별번호 12345 사업장의 2025년 1월 취득/상실 현황을 알려줘
```
### Python에서 직접 사용
```python
import asyncio
from mcp_nps_business_enrollment.api_client import NPSAPIClient
async def main():
async with NPSAPIClient() as client:
# 사업장 검색
result = await client.search_business(
wkpl_nm="삼성전자",
num_of_rows=5
)
print(f"Found {result['total_count']} businesses")
# 상세정보 조회
if result['items']:
seq = result['items'][0]['seq']
detail = await client.get_business_detail(seq=seq)
print(f"Detail: {detail}")
asyncio.run(main())
```
## 테스트
```bash
# 테스트 실행
uv run python tests/test_api.py
# pytest 사용
uv run pytest tests/
```
## API 제한사항
- 공공데이터포털 API 일일 호출 제한이 있을 수 있습니다
- 3인 이상 법인사업장 정보만 제공됩니다
- 매월 15일 이후 데이터가 갱신됩니다
- 사업자등록번호는 앞 6자리만 제공 (뒤 4자리는 마스킹)
## 알려진 한계점 및 이슈
### 1. 시계열 데이터 조회 불가
- **문제**: 한 회사의 여러 달 임직원 변동 추이를 한 번에 조회할 수 없음
- **원인**: API에서 `seq`는 사업장 고유번호가 아닌 월별 데이터 식별번호
- 동일 회사도 매월 다른 seq를 가짐 (예: 스페이스와이 202506월 seq=6500466, 202505월 seq=5919804)
- **현재 해결방법**: 각 월별로 개별 검색 후 seq를 찾아 조회해야 함
### 2. 대기업 본사 조회 어려움
- **문제**: 삼성전자 같은 대기업 본사가 검색되지 않음 (협력업체만 1,600개+ 검색됨)
- **가능한 원인**:
- 대기업은 지역별/사업부별로 별도 사업장 등록
- API에 등록된 정식 명칭이 다를 수 있음
- 일부 대기업 데이터는 제공하지 않을 가능성
### 3. 사업자등록번호 검색 한계
- **문제**: 사업자등록번호만으로는 특정 회사를 찾을 수 없음
- **원인**: API는 앞 6자리만 제공하며, 동일한 앞 6자리를 가진 회사가 수백 개 존재
- **예시**: 436860으로 검색 시 725개 회사 검색됨
- **해결방법**: 회사명 + 사업자등록번호 조합으로 검색
### 4. 데이터 제공 범위
- 최근 1년치 데이터만 제공 (2018.7.2부터 적용)
- 현재 데이터는 특정 월(예: 202506)까지만 제공되며, 이후 월은 조회 불가
### 5. API 응답 제한
- **한 번에 조회 가능한 최대 개수**: 100개
- **테스트 결과**: 100개까지는 정상, 150개 이상 요청 시 CLIENT_ERROR 발생
- **개선사항**: 검색 결과를 더 많이 보기 위해 `num_of_rows` 기본값을 10에서 100으로 변경
- 이전: 회사명 검색 시 10개만 표시 → 여러 회사 중 원하는 회사 찾기 어려움
- 현재: 100개 표시 → 더 많은 검색 결과를 한 번에 확인 가능
- **추가 데이터 필요 시**: 페이지네이션 활용 (pageNo 파라미터 사용)
## 향후 개선 계획 (TODO)
### 데이터베이스 기반 MCP 서버 구축
- [ ] [공공데이터포털 CSV 파일](https://www.data.go.kr/data/15083277/fileData.do)을 활용한 완전한 데이터베이스 구축
- 월별 CSV 파일 전체 다운로드 및 파싱
- SQLite/PostgreSQL 등 로컬 DB에 데이터 저장
- 과거 전체 기간 데이터 분석 가능
## 기여하기
프로젝트에 기여하고 싶으시다면 Pull Request를 보내주세요!
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 라이센스
MIT License - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.
## 문의
문제가 있거나 제안사항이 있으시면 [Issues](https://github.com/Koomook/mcp_NPS_BusinessEnrollment/issues)에 등록해주세요.
## 참고자료
- [국민연금공단 OpenAPI 활용가이드](https://www.data.go.kr/data/3046071/openapi.do)
- [MCP (Model Context Protocol)](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-nps-business-enrollment",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, business, enrollment, korea, mcp, nps, pension",
"author": null,
"author_email": "Dave Goobong Jeong <bongbonggg97@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6f/a7/ddb61bc230981d9869cd2b0df07cfdd72ce64af9dfbb2eb72a7c78ccf6f7/mcp_nps_business_enrollment-0.1.2.tar.gz",
"platform": null,
"description": "# MCP NPS Business Enrollment Server\n\n\uad6d\ubbfc\uc5f0\uae08 \uac00\uc785 \uc0ac\uc5c5\uc7a5 \ub0b4\uc5ed API\ub97c MCP(Model Context Protocol) \uc11c\ubc84\ub85c \uc81c\uacf5\ud558\ub294 Python \ud328\ud0a4\uc9c0\uc785\ub2c8\ub2e4.\n\n## \uc8fc\uc694 \uae30\ub2a5\n\n**\uae30\uc5c5 \uc784\uc9c1\uc6d0 \uc218 \ubc0f \uc608\uc0c1 \ud3c9\uade0 \uc6d4\uae09 \uc870\ud68c**\n- \uad6d\ubbfc\uc5f0\uae08 \uac00\uc785\uc790 \uc218\ub85c \uc2e4\uc81c \uc784\uc9c1\uc6d0 \uaddc\ubaa8 \ud30c\uc545\n- \ub2f9\uc6d4 \uace0\uc9c0\uae08\uc561 \uae30\ubc18 \uc608\uc0c1 \ud3c9\uade0 \uc6d4\uae09 \uacc4\uc0b0 (\ucd94\uc815\uac12)\n- \uc6d4\ubcc4 \uc785\uc0ac/\ud1f4\uc0ac \ud604\ud669 \ucd94\uc801\n\n## \uc791\ub3d9 \uc6d0\ub9ac\n\n```mermaid\ngraph LR\n A[Claude/MCP Client] --> B[MCP Server]\n B --> C[\uad6d\ubbfc\uc5f0\uae08\uacf5\ub2e8 API]\n C --> D[\uc0ac\uc5c5\uc7a5 \uc815\ubcf4]\n D --> B\n B --> E[\ub370\uc774\ud130 \ucc98\ub9ac<br/>\ud3c9\uade0 \uc6d4\uae09 \uacc4\uc0b0]\n E --> A\n```\n\n1. **MCP \ud074\ub77c\uc774\uc5b8\ud2b8** (Claude Desktop/Code)\uac00 \uc0ac\uc6a9\uc790 \uc694\uccad\uc744 \ubc1b\uc74c\n2. **MCP \uc11c\ubc84**\uac00 \uad6d\ubbfc\uc5f0\uae08\uacf5\ub2e8 OpenAPI\ub97c \ud638\ucd9c\n3. \ubc18\ud658\ub41c \ub370\uc774\ud130\uc5d0\uc11c \uac00\uc785\uc790\uc218, \ub2f9\uc6d4\uace0\uc9c0\uae08\uc561 \ucd94\ucd9c\n4. \uc608\uc0c1 \ud3c9\uade0 \uc6d4\uae09 \uacc4\uc0b0: `\ub2f9\uc6d4\uace0\uc9c0\uae08\uc561 \u00f7 \uac00\uc785\uc790\uc218 \u00f7 0.09 (\ubcf4\ud5d8\ub8cc\uc728)`\n5. \uacb0\uacfc\ub97c \uc0ac\uc6a9\uc790\uc5d0\uac8c \ubc18\ud658\n\n## \uac1c\uc694\n\n\uc774 \ud504\ub85c\uc81d\ud2b8\ub294 \uacf5\uacf5\ub370\uc774\ud130\ud3ec\ud138\uc5d0\uc11c \uc81c\uacf5\ud558\ub294 [\uad6d\ubbfc\uc5f0\uae08\uacf5\ub2e8\uc758 \uc0ac\uc5c5\uc7a5 \uc815\ubcf4\uc870\ud68c \uc11c\ube44\uc2a4](https://www.data.go.kr/data/3046071/openapi.do)\ub97c MCP \uc11c\ubc84\ub85c \uad6c\ud604\ud55c \uac83\uc785\ub2c8\ub2e4. Claude Desktop \ubc0f \uae30\ud0c0 MCP \ud638\ud658 \ud074\ub77c\uc774\uc5b8\ud2b8\uc5d0\uc11c \uad6d\ubbfc\uc5f0\uae08 \uac00\uc785 \uc0ac\uc5c5\uc7a5 \uc815\ubcf4\ub97c \uc27d\uac8c \uc870\ud68c\ud560 \uc218 \uc788\uc2b5\ub2c8\ub2e4.\n\n## MCP Tools\n\n1. **search_business** \n - \uc0ac\uc5c5\uc7a5 \uc815\ubcf4 \uc870\ud68c\n - \uc9c0\uc5ed\ubcc4, \uc0ac\uc5c5\uc7a5\uba85, \uc0ac\uc5c5\uc790\ub4f1\ub85d\ubc88\ud638\ub85c \uac80\uc0c9\n - \ud398\uc774\uc9c0\ub124\uc774\uc158 \uc9c0\uc6d0\n\n2. **get_business_detail** \n - \uc0ac\uc5c5\uc7a5 \uc0c1\uc138\uc815\ubcf4 \uc870\ud68c\n - \uc5c5\uc885\ucf54\ub4dc, \uac00\uc785\uc790\uc218, \ub2f9\uc6d4\uace0\uc9c0\uae08\uc561 \ub4f1 \uc0c1\uc138\uc815\ubcf4\n\n3. **get_period_status** \n - \uae30\uac04\ubcc4 \ud604\ud669 \uc815\ubcf4 \uc870\ud68c\n - \uc6d4\ubcc4 \ucde8\ub4dd\uc790/\uc0c1\uc2e4\uc790 \ud604\ud669\n\n## MCP \ud074\ub77c\uc774\uc5b8\ud2b8\uc5d0 \ube60\ub978 \uc124\uce58\n\n### \ud14c\uc2a4\ud2b8\uc6a9 API \ud0a4\n\n\ub2e4\uc74c \ud14c\uc2a4\ud2b8\uc6a9 API \ud0a4\ub97c \uc81c\uacf5\ud569\ub2c8\ub2e4. \uc544\ub798 \uc124\uce58 \uba85\ub839\uc5b4\uc5d0\uc11c \ubc14\ub85c \uc0ac\uc6a9\ud560 \uc218 \uc788\uc2b5\ub2c8\ub2e4:\n```\ncm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==\n```\n\n\u26a0\ufe0f **\uc911\uc694 \uc548\ub0b4**: \n- \uc774 \ud14c\uc2a4\ud2b8\uc6a9 API \ud0a4\ub294 **\ud558\ub8e8 \ucd1d 10,000\uac74**\uae4c\uc9c0\ub9cc \ud638\ucd9c \uac00\ub2a5\ud569\ub2c8\ub2e4\n- \uc5ec\ub7ec \uc0ac\uc6a9\uc790\uac00 \uacf5\uc720\ud558\ubbc0\ub85c **\uc5b8\uc81c\ub4e0\uc9c0 \ud638\ucd9c\uc774 \uc2e4\ud328\ud560 \uc218 \uc788\uc2b5\ub2c8\ub2e4**\n- \uc548\uc815\uc801\uc778 \uc0ac\uc6a9\uc744 \uc704\ud574\uc11c\ub294 [\uac1c\uc778 API \ud0a4 \ubc1c\uae09](#1-api-\ud0a4-\ubc1c\uae09)\uc744 \uad8c\uc7a5\ud569\ub2c8\ub2e4\n\n### Claude Desktop\n\n**\uac00\uc7a5 \uac04\ub2e8\ud55c \ubc29\ubc95 - PyPI \ud328\ud0a4\uc9c0 \uc0ac\uc6a9:**\n\n1. Claude Desktop \uc124\uc815 \ud30c\uc77c \uc5f4\uae30:\n - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. \ub2e4\uc74c \uc124\uc815 \ucd94\uac00 (\ud14c\uc2a4\ud2b8\uc6a9 API \ud0a4 \ud3ec\ud568):\n```json\n{\n \"mcpServers\": {\n \"nps-business\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-nps-business-enrollment\"],\n \"env\": {\n \"API_KEY\": \"cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==\"\n }\n }\n }\n}\n```\n\n3. Claude Desktop \uc7ac\uc2dc\uc791\n\n### Claude Code\n\n```bash\n# \ud14c\uc2a4\ud2b8\uc6a9 API \ud0a4\ub85c \uc124\uce58\nclaude mcp add nps-business \\\n --env API_KEY=\"cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==\" \\\n -- uvx mcp-nps-business-enrollment\n```\n\n### Codex CLI\n\nCodex CLI\uc5d0\uc11c MCP \uc11c\ubc84\ub97c \uc0ac\uc6a9\ud558\ub824\uba74 `~/.codex/config.toml` \ud30c\uc77c\uc744 \uc218\uc815\ud569\ub2c8\ub2e4:\n\n1. Codex CLI \uc124\uce58 (\ud544\uc694\ud55c \uacbd\uc6b0):\n```bash\nnpm install -g @openai/codex\n```\n\n2. \uc124\uc815 \ud30c\uc77c \ud3b8\uc9d1 `~/.codex/config.toml`:\n```toml\n# NPS Business Enrollment MCP Server \uc124\uc815\n[mcp_servers.nps-business]\ncommand = \"uvx\"\nargs = [\"mcp-nps-business-enrollment\"]\nenv = { API_KEY = \"cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==\" }\n```\n\n3. Codex \uc2e4\ud589:\n```bash\ncodex # \ud504\ub85c\uc81d\ud2b8 \ub514\ub809\ud1a0\ub9ac\uc5d0\uc11c \uc2e4\ud589\n```\n\n## \uac1c\ubc1c\uc790\uc6a9 \uc124\uce58\n\n### \ub85c\uceec \uac1c\ubc1c \ud658\uacbd\uc5d0\uc11c MCP \ud074\ub77c\uc774\uc5b8\ud2b8\uc5d0 \uc124\uce58\n\n\uc774 \ub808\ud3ec\uc9c0\ud1a0\ub9ac\ub97c \ud074\ub860\ud558\uc5ec \ub85c\uceec \uac1c\ubc1c \ubc84\uc804\uc744 MCP \ud074\ub77c\uc774\uc5b8\ud2b8\uc5d0 \uc9c1\uc811 \uc5f0\uacb0\ud560 \uc218 \uc788\uc2b5\ub2c8\ub2e4.\n\n#### 1. \ub808\ud3ec\uc9c0\ud1a0\ub9ac \ud074\ub860 \ubc0f \uc124\uc815\n\n```bash\n# \ub808\ud3ec\uc9c0\ud1a0\ub9ac \ud074\ub860\ngit clone https://github.com/Koomook/mcp_NPS_BusinessEnrollment.git\ncd mcp_NPS_BusinessEnrollment\n\n# uv\ub97c \uc0ac\uc6a9\ud55c \uc758\uc874\uc131 \uc124\uce58\nuv sync\n```\n\n#### 2. Claude Desktop\uc5d0 \ub85c\uceec \uac1c\ubc1c \ubc84\uc804 \uc5f0\uacb0\n\nClaude Desktop \uc124\uc815 \ud30c\uc77c\uc744 \uc5f4\uc5b4 \ub2e4\uc74c\uacfc \uac19\uc774 \uc124\uc815\ud569\ub2c8\ub2e4:\n\n```json\n{\n \"mcpServers\": {\n \"nps-business-dev\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"mcp-nps-business-enrollment\"],\n \"cwd\": \"/path/to/mcp_NPS_BusinessEnrollment\",\n \"env\": {\n \"API_KEY\": \"cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==\"\n }\n }\n }\n}\n```\n\n**\ucc38\uace0:** `cwd`\ub97c \uc2e4\uc81c \ud074\ub860\ud55c \ub514\ub809\ud1a0\ub9ac \uacbd\ub85c\ub85c \ubcc0\uacbd\ud558\uc138\uc694.\n\n#### 3. Claude Code\uc5d0 \ub85c\uceec \uac1c\ubc1c \ubc84\uc804 \uc5f0\uacb0\n\n```bash\n# \ud074\ub860\ud55c \ub514\ub809\ud1a0\ub9ac\uc5d0\uc11c \uc2e4\ud589\nclaude mcp add nps-business-dev \\\n --env API_KEY=\"cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==\" \\\n -- uv run --directory /path/to/mcp_NPS_BusinessEnrollment mcp-nps-business-enrollment\n```\n\n### PyPI \ud328\ud0a4\uc9c0\ub85c \uac1c\ubc1c\n\n```bash\n# PyPI\uc5d0\uc11c \uc124\uce58\npip install mcp-nps-business-enrollment\n\n# \ub610\ub294 uv \uc0ac\uc6a9 (\uad8c\uc7a5)\nuv pip install mcp-nps-business-enrollment\n```\n\n## \ud658\uacbd \uc124\uc815\n\n### 1. API \ud0a4 \ubc1c\uae09\n\n\uacf5\uacf5\ub370\uc774\ud130\ud3ec\ud138\uc5d0\uc11c \uc81c\uacf5\ud558\ub294 [\uad6d\ubbfc\uc5f0\uae08\uacf5\ub2e8\uc758 \uc0ac\uc5c5\uc7a5 \uc815\ubcf4\uc870\ud68c \uc11c\ube44\uc2a4](https://www.data.go.kr/data/3046071/openapi.do)\uc5d0\uc11c \"\uad6d\ubbfc\uc5f0\uae08 \uac00\uc785 \uc0ac\uc5c5\uc7a5 \ub0b4\uc5ed\" API \ud65c\uc6a9 \uc2e0\uccad \ud6c4 \uc778\uc99d\ud0a4\ub97c \ubc1c\uae09\ubc1b\uc2b5\ub2c8\ub2e4.\n\n### 2. \ud658\uacbd\ubcc0\uc218 \uc124\uc815 (\uac1c\ubc1c\uc6a9)\n\n\uac1c\ubc1c \ud658\uacbd\uc5d0\uc11c \ud14c\uc2a4\ud2b8\ud560 \ub54c\ub294 `.env` \ud30c\uc77c\uc744 \uc0dd\uc131\ud558\uace0 \ub2e4\uc74c \ub0b4\uc6a9\uc744 \uc785\ub825\ud569\ub2c8\ub2e4:\n\n```env\n# API \ud0a4 (\ud544\uc218)\nAPI_KEY=\"your_api_key_here\"\n\n# \ud14c\uc2a4\ud2b8\uc6a9 API \ud0a4 \uc608\uc2dc:\n# API_KEY=\"cm+2VqVacqFCywI02FjjnrdNN2TeQS0FE+JRKoO2FuEXGGjHImnWNHBAHWlrtaadj3D+Y87e5bfn6th8q3Nzkw==\"\n```\n\n**\ucc38\uace0:** API endpoint\ub294 \uc790\ub3d9\uc73c\ub85c \uc124\uc815\ub418\ubbc0\ub85c \ubcc4\ub3c4 \uc124\uc815\uc774 \ud544\uc694 \uc5c6\uc2b5\ub2c8\ub2e4.\n\n\n\n## \uc0ac\uc6a9 \uc608\uc2dc\n\n### MCP Client(Claude Desktop \ub4f1)\uc5d0\uc11c \uc0ac\uc6a9\n\n```\n\uc784\uc9c1\uc6d0 \uc218 \ubc0f \ud3c9\uade0 \uc6d4\uae09 \uc870\ud68c:\n\"\uc2a4\ud398\uc774\uc2a4\uc640\uc774\" \ud68c\uc0ac\uc758 \uc784\uc9c1\uc6d0 \uc218\uc640 \uc608\uc0c1 \ud3c9\uade0 \uc6d4\uae09\uc744 \uc54c\ub824\uc918\n\n\uc0ac\uc5c5\uc7a5\uba85\uc73c\ub85c \uac80\uc0c9:\n\"\uc0bc\uc131\uc804\uc790\"\ub77c\ub294 \uc774\ub984\uc774 \ud3ec\ud568\ub41c \uc0ac\uc5c5\uc7a5\uc744 \uac80\uc0c9\ud574\uc918\n\n\uc9c0\uc5ed\ubcc4 \uac80\uc0c9:\n\uc11c\uc6b8\ud2b9\ubcc4\uc2dc \uac15\ub0a8\uad6c\uc5d0 \uc788\ub294 \uc0ac\uc5c5\uc7a5\ub4e4\uc744 \ucc3e\uc544\uc918\n\n\uc0c1\uc138\uc815\ubcf4 \uc870\ud68c:\n\uc2dd\ubcc4\ubc88\ud638 12345\uc778 \uc0ac\uc5c5\uc7a5\uc758 \uc0c1\uc138\uc815\ubcf4\ub97c \ubcf4\uc5ec\uc918\n\n\uae30\uac04\ubcc4 \ud604\ud669:\n\uc2dd\ubcc4\ubc88\ud638 12345 \uc0ac\uc5c5\uc7a5\uc758 2025\ub144 1\uc6d4 \ucde8\ub4dd/\uc0c1\uc2e4 \ud604\ud669\uc744 \uc54c\ub824\uc918\n```\n\n### Python\uc5d0\uc11c \uc9c1\uc811 \uc0ac\uc6a9\n\n```python\nimport asyncio\nfrom mcp_nps_business_enrollment.api_client import NPSAPIClient\n\nasync def main():\n async with NPSAPIClient() as client:\n # \uc0ac\uc5c5\uc7a5 \uac80\uc0c9\n result = await client.search_business(\n wkpl_nm=\"\uc0bc\uc131\uc804\uc790\",\n num_of_rows=5\n )\n print(f\"Found {result['total_count']} businesses\")\n \n # \uc0c1\uc138\uc815\ubcf4 \uc870\ud68c\n if result['items']:\n seq = result['items'][0]['seq']\n detail = await client.get_business_detail(seq=seq)\n print(f\"Detail: {detail}\")\n\nasyncio.run(main())\n```\n\n## \ud14c\uc2a4\ud2b8\n\n```bash\n# \ud14c\uc2a4\ud2b8 \uc2e4\ud589\nuv run python tests/test_api.py\n\n# pytest \uc0ac\uc6a9\nuv run pytest tests/\n```\n\n## API \uc81c\ud55c\uc0ac\ud56d\n\n- \uacf5\uacf5\ub370\uc774\ud130\ud3ec\ud138 API \uc77c\uc77c \ud638\ucd9c \uc81c\ud55c\uc774 \uc788\uc744 \uc218 \uc788\uc2b5\ub2c8\ub2e4\n- 3\uc778 \uc774\uc0c1 \ubc95\uc778\uc0ac\uc5c5\uc7a5 \uc815\ubcf4\ub9cc \uc81c\uacf5\ub429\ub2c8\ub2e4\n- \ub9e4\uc6d4 15\uc77c \uc774\ud6c4 \ub370\uc774\ud130\uac00 \uac31\uc2e0\ub429\ub2c8\ub2e4\n- \uc0ac\uc5c5\uc790\ub4f1\ub85d\ubc88\ud638\ub294 \uc55e 6\uc790\ub9ac\ub9cc \uc81c\uacf5 (\ub4a4 4\uc790\ub9ac\ub294 \ub9c8\uc2a4\ud0b9)\n\n## \uc54c\ub824\uc9c4 \ud55c\uacc4\uc810 \ubc0f \uc774\uc288\n\n### 1. \uc2dc\uacc4\uc5f4 \ub370\uc774\ud130 \uc870\ud68c \ubd88\uac00\n- **\ubb38\uc81c**: \ud55c \ud68c\uc0ac\uc758 \uc5ec\ub7ec \ub2ec \uc784\uc9c1\uc6d0 \ubcc0\ub3d9 \ucd94\uc774\ub97c \ud55c \ubc88\uc5d0 \uc870\ud68c\ud560 \uc218 \uc5c6\uc74c\n- **\uc6d0\uc778**: API\uc5d0\uc11c `seq`\ub294 \uc0ac\uc5c5\uc7a5 \uace0\uc720\ubc88\ud638\uac00 \uc544\ub2cc \uc6d4\ubcc4 \ub370\uc774\ud130 \uc2dd\ubcc4\ubc88\ud638\n - \ub3d9\uc77c \ud68c\uc0ac\ub3c4 \ub9e4\uc6d4 \ub2e4\ub978 seq\ub97c \uac00\uc9d0 (\uc608: \uc2a4\ud398\uc774\uc2a4\uc640\uc774 202506\uc6d4 seq=6500466, 202505\uc6d4 seq=5919804)\n- **\ud604\uc7ac \ud574\uacb0\ubc29\ubc95**: \uac01 \uc6d4\ubcc4\ub85c \uac1c\ubcc4 \uac80\uc0c9 \ud6c4 seq\ub97c \ucc3e\uc544 \uc870\ud68c\ud574\uc57c \ud568\n\n### 2. \ub300\uae30\uc5c5 \ubcf8\uc0ac \uc870\ud68c \uc5b4\ub824\uc6c0\n- **\ubb38\uc81c**: \uc0bc\uc131\uc804\uc790 \uac19\uc740 \ub300\uae30\uc5c5 \ubcf8\uc0ac\uac00 \uac80\uc0c9\ub418\uc9c0 \uc54a\uc74c (\ud611\ub825\uc5c5\uccb4\ub9cc 1,600\uac1c+ \uac80\uc0c9\ub428)\n- **\uac00\ub2a5\ud55c \uc6d0\uc778**:\n - \ub300\uae30\uc5c5\uc740 \uc9c0\uc5ed\ubcc4/\uc0ac\uc5c5\ubd80\ubcc4\ub85c \ubcc4\ub3c4 \uc0ac\uc5c5\uc7a5 \ub4f1\ub85d\n - API\uc5d0 \ub4f1\ub85d\ub41c \uc815\uc2dd \uba85\uce6d\uc774 \ub2e4\ub97c \uc218 \uc788\uc74c\n - \uc77c\ubd80 \ub300\uae30\uc5c5 \ub370\uc774\ud130\ub294 \uc81c\uacf5\ud558\uc9c0 \uc54a\uc744 \uac00\ub2a5\uc131\n\n### 3. \uc0ac\uc5c5\uc790\ub4f1\ub85d\ubc88\ud638 \uac80\uc0c9 \ud55c\uacc4\n- **\ubb38\uc81c**: \uc0ac\uc5c5\uc790\ub4f1\ub85d\ubc88\ud638\ub9cc\uc73c\ub85c\ub294 \ud2b9\uc815 \ud68c\uc0ac\ub97c \ucc3e\uc744 \uc218 \uc5c6\uc74c\n- **\uc6d0\uc778**: API\ub294 \uc55e 6\uc790\ub9ac\ub9cc \uc81c\uacf5\ud558\uba70, \ub3d9\uc77c\ud55c \uc55e 6\uc790\ub9ac\ub97c \uac00\uc9c4 \ud68c\uc0ac\uac00 \uc218\ubc31 \uac1c \uc874\uc7ac\n- **\uc608\uc2dc**: 436860\uc73c\ub85c \uac80\uc0c9 \uc2dc 725\uac1c \ud68c\uc0ac \uac80\uc0c9\ub428\n- **\ud574\uacb0\ubc29\ubc95**: \ud68c\uc0ac\uba85 + \uc0ac\uc5c5\uc790\ub4f1\ub85d\ubc88\ud638 \uc870\ud569\uc73c\ub85c \uac80\uc0c9\n\n### 4. \ub370\uc774\ud130 \uc81c\uacf5 \ubc94\uc704\n- \ucd5c\uadfc 1\ub144\uce58 \ub370\uc774\ud130\ub9cc \uc81c\uacf5 (2018.7.2\ubd80\ud130 \uc801\uc6a9)\n- \ud604\uc7ac \ub370\uc774\ud130\ub294 \ud2b9\uc815 \uc6d4(\uc608: 202506)\uae4c\uc9c0\ub9cc \uc81c\uacf5\ub418\uba70, \uc774\ud6c4 \uc6d4\uc740 \uc870\ud68c \ubd88\uac00\n\n### 5. API \uc751\ub2f5 \uc81c\ud55c\n- **\ud55c \ubc88\uc5d0 \uc870\ud68c \uac00\ub2a5\ud55c \ucd5c\ub300 \uac1c\uc218**: 100\uac1c\n- **\ud14c\uc2a4\ud2b8 \uacb0\uacfc**: 100\uac1c\uae4c\uc9c0\ub294 \uc815\uc0c1, 150\uac1c \uc774\uc0c1 \uc694\uccad \uc2dc CLIENT_ERROR \ubc1c\uc0dd\n- **\uac1c\uc120\uc0ac\ud56d**: \uac80\uc0c9 \uacb0\uacfc\ub97c \ub354 \ub9ce\uc774 \ubcf4\uae30 \uc704\ud574 `num_of_rows` \uae30\ubcf8\uac12\uc744 10\uc5d0\uc11c 100\uc73c\ub85c \ubcc0\uacbd\n - \uc774\uc804: \ud68c\uc0ac\uba85 \uac80\uc0c9 \uc2dc 10\uac1c\ub9cc \ud45c\uc2dc \u2192 \uc5ec\ub7ec \ud68c\uc0ac \uc911 \uc6d0\ud558\ub294 \ud68c\uc0ac \ucc3e\uae30 \uc5b4\ub824\uc6c0\n - \ud604\uc7ac: 100\uac1c \ud45c\uc2dc \u2192 \ub354 \ub9ce\uc740 \uac80\uc0c9 \uacb0\uacfc\ub97c \ud55c \ubc88\uc5d0 \ud655\uc778 \uac00\ub2a5\n- **\ucd94\uac00 \ub370\uc774\ud130 \ud544\uc694 \uc2dc**: \ud398\uc774\uc9c0\ub124\uc774\uc158 \ud65c\uc6a9 (pageNo \ud30c\ub77c\ubbf8\ud130 \uc0ac\uc6a9)\n\n## \ud5a5\ud6c4 \uac1c\uc120 \uacc4\ud68d (TODO)\n\n### \ub370\uc774\ud130\ubca0\uc774\uc2a4 \uae30\ubc18 MCP \uc11c\ubc84 \uad6c\ucd95\n- [ ] [\uacf5\uacf5\ub370\uc774\ud130\ud3ec\ud138 CSV \ud30c\uc77c](https://www.data.go.kr/data/15083277/fileData.do)\uc744 \ud65c\uc6a9\ud55c \uc644\uc804\ud55c \ub370\uc774\ud130\ubca0\uc774\uc2a4 \uad6c\ucd95\n - \uc6d4\ubcc4 CSV \ud30c\uc77c \uc804\uccb4 \ub2e4\uc6b4\ub85c\ub4dc \ubc0f \ud30c\uc2f1\n - SQLite/PostgreSQL \ub4f1 \ub85c\uceec DB\uc5d0 \ub370\uc774\ud130 \uc800\uc7a5\n - \uacfc\uac70 \uc804\uccb4 \uae30\uac04 \ub370\uc774\ud130 \ubd84\uc11d \uac00\ub2a5\n\n## \uae30\uc5ec\ud558\uae30\n\n\ud504\ub85c\uc81d\ud2b8\uc5d0 \uae30\uc5ec\ud558\uace0 \uc2f6\uc73c\uc2dc\ub2e4\uba74 Pull Request\ub97c \ubcf4\ub0b4\uc8fc\uc138\uc694!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## \ub77c\uc774\uc13c\uc2a4\n\nMIT License - \uc790\uc138\ud55c \ub0b4\uc6a9\uc740 [LICENSE](LICENSE) \ud30c\uc77c\uc744 \ucc38\uc870\ud558\uc138\uc694.\n\n## \ubb38\uc758\n\n\ubb38\uc81c\uac00 \uc788\uac70\ub098 \uc81c\uc548\uc0ac\ud56d\uc774 \uc788\uc73c\uc2dc\uba74 [Issues](https://github.com/Koomook/mcp_NPS_BusinessEnrollment/issues)\uc5d0 \ub4f1\ub85d\ud574\uc8fc\uc138\uc694.\n\n## \ucc38\uace0\uc790\ub8cc\n\n- [\uad6d\ubbfc\uc5f0\uae08\uacf5\ub2e8 OpenAPI \ud65c\uc6a9\uac00\uc774\ub4dc](https://www.data.go.kr/data/3046071/openapi.do)\n- [MCP (Model Context Protocol)](https://modelcontextprotocol.io)\n- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Korea National Pension Service business enrollment API",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/Koomook/mcp_NPS_BusinessEnrollment/issues",
"Documentation": "https://github.com/Koomook/mcp_NPS_BusinessEnrollment#readme",
"Homepage": "https://github.com/Koomook/mcp_NPS_BusinessEnrollment",
"Repository": "https://github.com/Koomook/mcp_NPS_BusinessEnrollment"
},
"split_keywords": [
"api",
" business",
" enrollment",
" korea",
" mcp",
" nps",
" pension"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1122817d6b1889a5649c89602de04e08b32c712431b8066de5e3a42ca97a087a",
"md5": "d3636710e30de78b0b2a59e97c59cd65",
"sha256": "8e79d50901ddc4ede496a9e1dbfc8e65a050582dc38a70d025240344ad364741"
},
"downloads": -1,
"filename": "mcp_nps_business_enrollment-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d3636710e30de78b0b2a59e97c59cd65",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 13034,
"upload_time": "2025-08-15T16:39:35",
"upload_time_iso_8601": "2025-08-15T16:39:35.997282Z",
"url": "https://files.pythonhosted.org/packages/11/22/817d6b1889a5649c89602de04e08b32c712431b8066de5e3a42ca97a087a/mcp_nps_business_enrollment-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6fa7ddb61bc230981d9869cd2b0df07cfdd72ce64af9dfbb2eb72a7c78ccf6f7",
"md5": "d0352e6fe9bc2e92f1ae193a326057dd",
"sha256": "8e61f6d29ad0348f45b920ef077d2b2eb4bf604ab8f9b5bdaa81feffc8eaf6d7"
},
"downloads": -1,
"filename": "mcp_nps_business_enrollment-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "d0352e6fe9bc2e92f1ae193a326057dd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19384,
"upload_time": "2025-08-15T16:39:36",
"upload_time_iso_8601": "2025-08-15T16:39:36.991412Z",
"url": "https://files.pythonhosted.org/packages/6f/a7/ddb61bc230981d9869cd2b0df07cfdd72ce64af9dfbb2eb72a7c78ccf6f7/mcp_nps_business_enrollment-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 16:39:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Koomook",
"github_project": "mcp_NPS_BusinessEnrollment",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mcp-nps-business-enrollment"
}
JSON
