Nara MCP Server (나라장터 입찰공고 검색)

MCP server for searching Korean government procurement bid notices from G2B (나라장터 - Nara Jangteo).

Features

• 🔍 키워드 검색: 최근 7일간 용역 입찰공고를 키워드로 검색
• 📅 자동 필터링: 마감되지 않은 공고만 자동 필터링
• 📎 파일 추출: 제안요청서(RFP) 자동 다운로드 및 텍스트 추출
• 🏢 맞춤형 추천: 부서 프로필 기반 Top 5 입찰공고 추천
• 📄 다형식 지원: HWP, HWPX, PDF, DOCX, XLSX, ZIP 파일 자동 처리
• 🎯 전략 분석: 첨부파일 기반 입찰 전략 제안

Prerequisites

1. API 키 발급 (필수)

나라장터 API를 사용하려면 공공데이터포털에서 API 키를 발급받아야 합니다.

발급 절차:

1. 공공데이터포털 접속 및 회원가입
2. 검색창에 "조달청_나라장터 입찰공고정보서비스" 검색
3. "조달청_나라장터 입찰공고정보서비스" 선택
4. 활용신청 클릭 (즉시 승인 또는 승인 대기)
5. 마이페이지 > 개발계정 에서 ServiceKey 확인 (일반 인증키 Decoding을 사용하면 됩니다.)

2. Python 환경

• Python 3.10 이상 필요

Installation

Option 1: From Source (권장)

git clone https://github.com/Datajang/narajangteo_mcp_server.git
cd narajangteo_mcp_server
pip install -r requirements.txt

Option 2: From PyPI (향후 제공 예정)

pip install nara-mcp-server

Configuration

Claude Desktop

Claude Desktop의 설정 파일을 수정하여 MCP 서버를 연결합니다.

설정 파일 위치:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

설정 예시:

{
  "mcpServers": {
    "nara-jangteo": {
      "command": "python",
      "args": ["C:\\absolute\\path\\to\\naraMcp\\server.py"],
      "env": {
        "NARA_API_KEY": "여기에_발급받은_ServiceKey_입력"
      }
    }
  }
}

중요 사항:

• args의 경로는 절대 경로로 지정
• Windows 경로는 \\로 구분 (예: C:\\Users\\...)
• NARA_API_KEY에 발급받은 ServiceKey 입력

Other MCP Clients

Continue, Cline 등 다른 MCP 클라이언트에서도 동일한 방식으로 환경변수 설정:

{
  "env": {
    "NARA_API_KEY": "your_service_key_here"
  }
}

Available Tools

1. get_bids_by_keyword

키워드로 최근 7일간 용역 입찰공고를 검색합니다.

파라미터:

• keyword (필수): 검색 키워드 (예: "인공지능", "AI", "플랫폼", "시스템 구축")

반환 정보:

• 공고명 (bidNtceNm)
• 공고번호 (bidNtceNo)
• 수요기관 (dminsttNm)
• 마감일시 (bidClseDt) - 마감되지 않은 공고만
• 제안요청서 링크 (ntceSpecDocUrl1)

예시 질문:

나라장터에서 "인공지능" 키워드로 입찰공고를 검색해줘

AI 관련 정부 프로젝트 입찰 공고를 찾아줘

---

2. recommend_bids_for_dept

부서/팀 프로필을 기반으로 맞춤형 입찰공고를 추천합니다 (최대 30개 검색 후 Top 5 선정).

파라미터:

• keyword (필수): 검색 키워드
• department_profile (필수): 부서/팀 설명 (예: "UI/UX 디자인팀", "AI/ML 개발팀")

예시 질문:

우리 팀은 클라우드 인프라 구축 전문팀이야. "클라우드" 키워드로 우리 팀에 맞는 입찰공고 추천해줘

데이터베이스 마이그레이션 전문가인데, "DB" 키워드로 적합한 입찰공고를 찾아줘

---

3. analyze_bid_detail

입찰공고 첨부파일(제안요청서)을 다운로드하고 텍스트를 추출하여 분석합니다.

파라미터:

• file_url (필수): 첨부파일 URL (검색 결과의 ntceSpecDocUrl1)
• filename (필수): 파일명 (검색 결과의 ntceSpecFileNm1)
• department_profile (선택): 부서 설명 (입력 시 전략 분석 포함)

지원 형식:

• HWP/HWPX: 한글 문서 (주요 형식)
• PDF: 이미지 기반 PDF는 제외
• DOCX: MS Word 문서
• XLSX: Excel 스프레드시트
• ZIP: 자동으로 내부 파일 선택 (제안요청서 우선)

예시 질문:

위 공고의 첨부파일을 분석해줘. 우리 팀은 AI 개발팀이야.

분석 결과:

• Fit Score (0-100): 팀과 프로젝트의 적합도
• Core Tasks: 팀이 수행할 핵심 업무
• Winning Strategy: 입찰 전략 3가지
• Risk Factors: 위험 요소 (기술스택, 일정, 페널티 등)

Usage Examples

기본 검색

Q: 나라장터에서 "시스템 개발" 키워드로 입찰공고를 검색해줘

A: 🔍 Found 15 bid notice(s) total, 8 still open for keyword: '시스템 개발'
   📅 Search period: 20260109 ~ 20260116

   ## 1. AI 기반 고객관리 시스템 개발 용역
      📌 공고번호: 20260112345-00
      🏢 수요기관: 서울시청
      ⏰ 마감일시: 202601201430
      📎 제안요청서: [다운로드 링크]

맞춤형 추천

Q: 우리 팀은 React 기반 웹 프론트엔드 개발 전문팀이야. "플랫폼 구축" 키워드로 우리 팀에 맞는 입찰공고 Top 5를 추천해줘

A: 🎯 Department-Filtered Bid Search Results

   📋 Department Profile: React 기반 웹 프론트엔드 개발 전문팀
   🔍 Keyword: 플랫폼 구축
   📊 Total Open Bids: 22 (out of 30 total)

   **Top 5 Recommendations:**

   1. ✅ 시민참여 플랫폼 구축 (적합도 95점)
      - React/TypeScript 기반 웹 프론트엔드 구축 명시
      - UI/UX 디자인 역량 중요
   ...

전략 분석

Q: 위 1번 공고의 첨부파일을 분석해줘

A: 📄 Bid Document Analysis

   📎 File: 제안요청서_시민참여플랫폼.hwp

   ## Strategic Analysis

   **Fit Score:** 92/100
   - React 18, TypeScript, Tailwind CSS 기술스택 요구
   - 반응형 웹 디자인 및 접근성(WCAG 2.1) 준수 필요

   **Core Tasks:**
   1. React 기반 SPA(Single Page Application) 개발
   2. 사용자 대시보드 및 관리자 콘솔 UI 구현
   3. REST API 연동 및 상태 관리 (Redux/Zustand)

   **Winning Strategy:**
   1. 포트폴리오에서 정부기관 반응형 웹 사례 강조
   2. 접근성 준수 경험 및 웹 표준 인증서 제시
   3. React 성능 최적화 기법 (Code Splitting, Lazy Loading) 강조

   **Risk Factors:**
   - ⚠️ 개발 기간 3개월로 촉박함 (일반적으로 4-5개월 소요)
   - ⚠️ 지체상금: 일 0.1% (최대 10%)
   - ✅ 기술스택은 팀 역량과 100% 일치

Troubleshooting

1. ValueError: NARA_API_KEY environment variable is required

원인: API 키가 환경변수로 설정되지 않았습니다.

해결 방법:

• Claude Desktop 설정 파일의 env 섹션에 NARA_API_KEY 추가
• Claude Desktop 재시작

2. API Error (Code: 03 - No Data)

원인: 검색 결과가 없거나, 최근 7일간 해당 키워드의 공고가 없습니다.

해결 방법:

• 다른 키워드로 검색 시도
• 검색 기간을 확장하고 싶다면 개발자에게 문의

3. API Error (Code: 20 - Access Denied)

원인: API 키가 잘못되었거나 활용신청이 승인되지 않았습니다.

해결 방법:

• 공공데이터포털 > 마이페이지에서 ServiceKey 확인
• 활용신청 승인 여부 확인

4. HWP 파일 추출 실패

원인: DRM/암호화된 HWP 파일이거나 비표준 인코딩입니다.

해결 방법:

• 원본 링크에서 수동 다운로드 시도
• PDF 버전 파일이 있는지 확인

API Information

• 데이터 출처: 조달청 나라장터 (Korea Public Procurement Service)
• API 서비스: BidPublicInfoService
• 엔드포인트: getBidPblancListInfoServcPPSSrch
• 공고 유형: 용역 (Service) - 컨설팅, 개발, SI 프로젝트
• 검색 기간: 최근 7일 (마감되지 않은 공고 비율 최적화)
• 필터링: 마감일시 기준 자동 필터링

참고:

• 물품 공고: 엔드포인트 변경 필요 (getBidPblancListInfoThngPPSSrch)
• 공사 공고: 엔드포인트 변경 필요 (getBidPblancListInfoCnstwkPPSSrch)

Technical Stack

• Python: 3.10+
• MCP SDK: mcp[cli] - Model Context Protocol server framework
• HTTP Client: httpx - Async HTTP requests
• File Extraction:
  • olefile - HWP (MS OLE format)
  • pypdf - PDF text extraction
  • python-docx - DOCX parsing
  • openpyxl - XLSX reading

Project Structure

naraMcp/
├── server.py              # Main MCP server
├── file_extractor.py      # Multi-format file text extraction
├── pyproject.toml         # Python project metadata
├── requirements.txt       # Python dependencies
├── README.md              # This file
├── CLAUDE.md              # Developer guide
├── SMITHERY_GUIDE.md      # Publishing guide
└── LICENSE                # MIT License

Development

Local Testing

# Set environment variable
export NARA_API_KEY="your_service_key_here"  # MacOS/Linux
set NARA_API_KEY=your_service_key_here       # Windows

# Run server
python server.py

Testing with MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run with inspector
mcp-inspector python server.py

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes with clear commit messages
4. Test thoroughly with real API calls
5. Submit a Pull Request

License

MIT License - see LICENSE file for details

Author

Datajang (GitHub)

Links

• Repository: https://github.com/Datajang/nara-mcp-server
• Issues: https://github.com/Datajang/nara-mcp-server/issues
• 공공데이터포털: https://www.data.go.kr/
• 나라장터: https://www.g2b.go.kr/

Acknowledgments

• 조달청 나라장터 for providing the public API
• Anthropic for the MCP protocol
• Korean government for open data initiatives