mcp-nps-business-enrollment 0.1.0

MCP server for Korea National Pension Service business enrollment API

MCP NPS Business Enrollment Server

국민연금 가입 사업장 내역 API를 MCP(Model Context Protocol) 서버로 제공하는 Python 패키지입니다.

개요

이 프로젝트는 공공데이터포털에서 제공하는 국민연금공단의 사업장 정보조회 서비스를 MCP 서버로 구현한 것입니다. Claude Desktop 및 기타 MCP 호환 클라이언트에서 국민연금 가입 사업장 정보를 쉽게 조회할 수 있습니다.

주요 기능

제공하는 MCP Tools

1. search_business - 사업장 정보 조회

   • 지역별, 사업장명, 사업자등록번호로 검색
   • 페이지네이션 지원

2. get_business_detail - 사업장 상세정보 조회

   • 업종코드, 가입자수, 당월고지금액 등 상세정보

3. get_period_status - 기간별 현황 정보 조회

   • 월별 취득자/상실자 현황

설치

PyPI에서 설치 (패키지 배포 후)

pip install mcp-nps-business-enrollment

개발 환경 설정 (uv 사용)

# 프로젝트 클론
git clone https://github.com/yourusername/mcp-nps-business-enrollment.git
cd mcp-nps-business-enrollment

# uv를 사용한 개발 환경 설정
uv sync

환경 설정

1. API 키 발급

공공데이터포털에서 "국민연금 가입 사업장 내역" API 활용 신청 후 인증키를 발급받습니다.

2. 환경변수 설정

.env 파일을 생성하고 다음 내용을 입력합니다:

# API 엔드포인트
API_ENDPOINT="https://apis.data.go.kr/B552015/NpsBplcInfoInqireServiceV2"

# URL 인코딩된 API 키 (브라우저에서 사용)
ENCODING_API_KEY="your_url_encoded_api_key_here"

# 디코딩된 API 키 (일반 사용)
DECODING_API_KEY="your_decoded_api_key_here"

Claude Desktop 설정

1. 자동 설치 (권장)

# npx를 사용한 한 줄 설치
npx @modelcontextprotocol/create-typescript@latest add-server nps-business --python-path $(which python) --script-path $(pwd)/src/mcp_nps_business_enrollment/server.py

# 또는 uv를 사용한 설치
uv run mcp install src/mcp_nps_business_enrollment/server.py

2. 개발 모드 실행

uv run mcp dev src/mcp_nps_business_enrollment/server.py

3. 수동 설정 (대체 방법)

Claude Desktop의 설정 파일에 직접 추가:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nps-business": {
      "command": "uv",
      "args": ["run", "mcp-nps-server"],
      "env": {
        "API_ENDPOINT": "https://apis.data.go.kr/B552015/NpsBplcInfoInqireServiceV2",
        "ENCODING_API_KEY": "your_encoded_key",
        "DECODING_API_KEY": "your_decoded_key"
      }
    }
  }
}

Claude Code 설정

1. Claude Code 명령어로 설치 (권장)

프로젝트 디렉토리에서 다음 명령어를 실행합니다:

# User scope로 설치 (모든 프로젝트에서 사용 가능)
claude mcp add nps-business -s user -- uv run --directory $(pwd) mcp-nps-server

# 또는 Project scope로 설치 (현재 프로젝트에서만 사용)
claude mcp add nps-business -s project -- uv run --directory $(pwd) mcp-nps-server

설치 후 Claude Code를 재시작하면 MCP 서버가 자동으로 연결됩니다.

2. MCP 서버 관리 명령어

# 설치된 MCP 서버 목록 확인
claude mcp list

# MCP 서버 제거
claude mcp remove nps-business

# MCP 서버 테스트
claude mcp get nps-business

3. 수동 설정 (대체 방법)

Claude Code의 설정 파일에 직접 추가:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux/WSL: ~/.claude.json

{
  "mcpServers": {
    "nps-business": {
      "command": "uv",
      "args": ["run", "mcp-nps-server"],
      "env": {
        "API_ENDPOINT": "https://apis.data.go.kr/B552015/NpsBplcInfoInqireServiceV2",
        "ENCODING_API_KEY": "your_encoded_key",
        "DECODING_API_KEY": "your_decoded_key"
      }
    }
  }
}

사용 예시

Claude Desktop에서 사용

사업장명으로 검색:
"삼성전자"라는 이름이 포함된 사업장을 검색해줘

지역별 검색:
서울특별시 강남구에 있는 사업장들을 찾아줘

상세정보 조회:
식별번호 12345인 사업장의 상세정보를 보여줘

기간별 현황:
식별번호 12345 사업장의 2025년 1월 취득/상실 현황을 알려줘

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())

테스트

# 테스트 실행
uv run python tests/test_api.py

# pytest 사용
uv run pytest tests/

API 제한사항

• 공공데이터포털 API 일일 호출 제한이 있을 수 있습니다
• 3인 이상 법인사업장 정보만 제공됩니다
• 매월 15일 이후 데이터가 갱신됩니다

기여하기

프로젝트에 기여하고 싶으시다면 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 파일을 참조하세요.

문의

문제가 있거나 제안사항이 있으시면 Issues에 등록해주세요.

참고자료

• 국민연금공단 OpenAPI 활용가이드
• MCP (Model Context Protocol)
• MCP Python SDK