나라장터 입찰공고 MCP server

<!-- mcp-name: io.github.opendata-kr/narajangteo-bid-mcp -->

@opendata-kr/narajangteo-bid-mcp

나라장터 입찰공고정보서비스(공공데이터포털 data.go.kr) Open API를 감싼 로컬 MCP 서버.

Claude Desktop 등 MCP 클라이언트에서 입찰공고를 자연어로 검색하고 조회한다. 예를 들어 이렇게 물어볼 수 있다.

• "이번 주 올라온 용역 입찰 공고를 찾아줘"
• "인천광역시에서 추정가격 5억 원 이상인 공사 입찰을 검색해줘"
• "입찰공고번호 R25BK00932003 상세를 알려줘"
• "그 공고의 기초금액과 참가 가능 지역을 알려줘"
• "그 공고의 첨부파일을 내려받아 제안요청서 내용을 요약해줘"
• "그 공고 첨부 중 과업지시서 본문을 읽어줘"

특징

• 4개 업무구분 병렬 검색: 공사/용역/물품/외자를 한 번에 조회한다. 업무구분 미지정 시 기타(etc)를 제외한 4구분(공사/용역/물품/외자)을 동시 검색하며, 기타공고는 bidKind에 etc를 명시한다.
• 첨부 다운로드·본문 읽기: 공고 첨부(공고문·규격서·제안요청서 등)를 디스크에 내려받고 ZIP은 풀어 파일 목록을 만든 뒤(downloadattachments), 필요한 파일의 본문(HWPX·구형 HWP·구형 DOC)을 목록 인덱스로 읽는다(readattachment).
• 부분 실패 표면화: 일부 구분 조회가 실패해도 나머지 결과를 반환하고, 실패한 구분은 오류 메시지로 드러낸다(조용한 누락 없음).
• data.go.kr 에러코드 한국어화: 인증키 만료, 트래픽 초과 등 결과코드를 조치 가능한 한국어 메시지로 정규화한다.
• 이중 인코딩 방어: Encoding 키를 잘못 넣으면 경고하고, 요청은 한 번만 인코딩한다.
• 타임아웃: API 호출에 타임아웃을 둔다.

준비물

• Node.js 24 이상 (.nvmrc = lts/krypton).
• data.go.kr 인증키:

1. 공공데이터포털에서 나라장터 입찰공고정보서비스를 활용신청해 [승인]을 받는다. 인증키는 계정당 하나지만, 각 API는 저마다 활용신청 승인이 있어야 그 API에서 인증된다. 서비스키가 있어도 이 API를 활용신청하지 않으면 인증 오류(코드 30)가 난다.
2. 마이페이지 → 활용신청 현황 → 개발계정 상세에서 Decoding 서비스키를 복사한다.
3. 같은 DATAGOKRSERVICEKEY는 같은 계정으로 활용신청한 다른 data.go.kr API에도 재사용된다.

[!TIP]

공공데이터포털이 처음이라면 활용신청부터 인증키 복사까지 그림으로 따라 하는 data.go.kr 인증키 발급 가이드를 참고한다.

서비스키는 반드시 Decoding(원본) 키를 넣는다. Encoding(%2B 등 포함) 키를 넣으면 이중 인코딩으로 인증 오류(코드 30)가 난다.

MCP 클라이언트 설정

MCP 클라이언트에 아래 config를 추가한다:

{
  "mcpServers": {
    "narajangteo-bid": {
      "command": "npx",
      "args": ["-y", "@opendata-kr/narajangteo-bid-mcp@latest"],
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
    }
  }
}

[!NOTE]

@opendata-kr/narajangteo-bid-mcp@latest를 쓰면 클라이언트가 항상 최신 버전을 받는다.

[!IMPORTANT]

DATAGOKRSERVICEKEY(필수, Decoding 원본 키)가 없으면 첫 호출이 인증 오류(코드 30)로 실패한다. 위 config의 env에 키를 넣는다. 원클릭 버튼이나 env를 config에 담지 못하는 클라이언트는 설치 후 셸 환경변수로 DATAGOKRSERVICEKEY를 설정한다.

클라이언트별 설정

Amp https://ampcode.com/manual#mcp 의 안내를 따르고 위 config를 사용한다. CLI로도 추가할 수 있다:

amp mcp add narajangteo-bid -- npx -y @opendata-kr/narajangteo-bid-mcp@latest

이후 생성된 설정의 env(또는 셸 환경변수)에 DATAGOKRSERVICEKEY를 추가한다.

Antigravity

Antigravity 문서의 커스텀 MCP 서버 추가 방법을 따라 아래 config를 MCP servers 설정에 넣는다:

{
  "mcpServers": {
    "narajangteo-bid": {
      "command": "npx",
      "args": ["-y", "@opendata-kr/narajangteo-bid-mcp@latest"],
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
    }
  }
}

Claude Code

Claude Code CLI로 서버를 추가한다 (가이드):

claude mcp add narajangteo-bid --scope user --env DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 -- npx -y @opendata-kr/narajangteo-bid-mcp@latest

Cline https://docs.cline.bot/mcp/configuring-mcp-servers 의 안내를 따르고 위 config를 사용한다.

Codex MCP 설정 가이드를 따르고 위 config를 사용한다. Codex CLI로도 추가할 수 있다:

Shortened. The full README is on GitHub.