@opendata-kr/narajangteo-bid-mcp

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

npm version CI node license

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

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

특징

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

준비물

• Node.js 24 이상 (.nvmrc = lts/krypton).
• data.go.kr 인증키:
  1. 공공데이터포털에서 나라장터 입찰공고정보서비스를 활용신청해 [승인]을 받는다. 인증키는 계정당 하나지만, 각 API는 저마다 활용신청 승인이 있어야 그 API에서 인증된다. 서비스키가 있어도 이 API를 활용신청하지 않으면 인증 오류(코드 30)가 난다.
  2. 마이페이지 → 활용신청 현황 → 개발계정 상세에서 Decoding 서비스키를 복사한다.
  3. 같은 DATA_GO_KR_SERVICE_KEY는 같은 계정으로 활용신청한 다른 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] DATA_GO_KR_SERVICE_KEY(필수, Decoding 원본 키)가 없으면 첫 호출이 인증 오류(코드 30)로 실패한다. 위 config의 env에 키를 넣는다. 원클릭 버튼이나 env를 config에 담지 못하는 클라이언트는 설치 후 셸 환경변수로 DATA_GO_KR_SERVICE_KEY를 설정한다.

클라이언트별 설정

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

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

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

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

[mcp_servers.narajangteo-bid]
command = "cmd"
args = ["/c", "npx", "-y", "@opendata-kr/narajangteo-bid-mcp@latest"]
env = { DATA_GO_KR_SERVICE_KEY = "발급받은_Decoding_키" }

cmd mcp add narajangteo-bid --scope user npx -y @opendata-kr/narajangteo-bid-mcp@latest

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

copilot

/mcp add

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

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

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

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

gemini mcp add -s user narajangteo-bid npx -y @opendata-kr/narajangteo-bid-mcp@latest

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

DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 mcp-proxy --transport streamablehttp --port 8080 -- npx -y @opendata-kr/narajangteo-bid-mcp@latest

[[mcp_servers]]
name = "narajangteo-bid"
transport = "stdio"
command = "npx"
args = ["-y", "@opendata-kr/narajangteo-bid-mcp@latest"]
env = { DATA_GO_KR_SERVICE_KEY = "발급받은_Decoding_키" }

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "narajangteo-bid": {
      "type": "local",
      "command": ["npx", "-y", "@opendata-kr/narajangteo-bid-mcp@latest"],
      "environment": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
    }
  }
}

qodercli mcp add narajangteo-bid -- npx @opendata-kr/narajangteo-bid-mcp@latest

qodercli mcp add -s user narajangteo-bid -- npx @opendata-kr/narajangteo-bid-mcp@latest

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

DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 mcp-proxy --transport streamablehttp --port 8080 -- npx -y @opendata-kr/narajangteo-bid-mcp@latest

발견성

이 서버는 MCP 레지스트리에 io.github.opendata-kr/narajangteo-bid-mcp로 기술된다. registry.modelcontextprotocol.io를 지원하는 클라이언트에서 검색·설치할 수 있다.

환경변수

도구

10개 도구 중 8개는 읽기 전용 조회(readOnlyHint: true)다. download_attachments·read_attachment는 첨부 파일을 디스크에 저장할 수 있어 읽기 전용이 아니다(readOnlyHint: false). 업무구분·항목별 병렬 조회 도구는 results에 조회 단위(업무구분 또는 항목 라벨)마다 성공 시 { status: "ok", totalCount, invalidCount, items }, 실패 시 { status: "error", error }를 담는다. 일부가 실패해도 나머지 결과는 반환하며(부분 실패 표면화), anySucceeded는 하나라도 성공했는지를 나타낸다. invalidCount는 응답 스키마 검증에서 탈락해 items에서 제외된 건수다. 0이 아니면 API 응답 필드가 예고 없이 바뀐 신호이므로 이슈로 알려주면 반영한다. 병렬 조회는 조회 단위 수만큼 API 요청을 소모하므로 업무구분을 알면 지정해 인증키 일일 트래픽을 아낀다.

search_bid_notices

키워드, 기간, 기관, 지역, 업종, 추정가격으로 입찰공고를 검색한다. 업무구분 미지정 시 기타(etc) 제외 4구분(공사/용역/물품/외자)을 병렬 검색한다.

조회창(startDate~`endDate`)은 최대 31일이다. 하나만 지정하면 그 날짜를 기준으로 30일 창을 채운다.

반환: { query, anySucceeded, results }. results는 업무구분별 BidNotice[]를 담는다.

get_bid_notice

입찰공고번호로 단건 조회한다. 업무구분 미지정 시 기타(etc)를 제외한 4구분에서 순차 조회하며, 기타공고는 bidKind에 etc를 명시한다.

반환: { found, bidKind, notice, searchedKinds, errors }. 찾으면 found: true와 notice(BidNotice), 못 찾으면 found: false. errors는 조회 중 발생한 오류 메시지다.

get_bid_basis_amount

입찰공고번호로 기초금액·평가기준금액·예비가격범위율을 조회한다. 기초금액은 물품·공사·용역 3구분만 존재한다(외자·기타 없음).

반환: { bidNtceNo, anySucceeded, results }. results는 업무구분별 BidBasisAmount[]를 담는다.

get_bid_evaluation

입찰공고번호로 낙찰가 산정 산식A(국민연금·건강보험료 등 합산항목)와 평가대상 주력분야를 조회한다. 업무구분 구분 없이 단일 조회한다.

반환: { bidNtceNo, anySucceeded, results }. results는 priceFormula(산식A)와 targetField(평가주력분야) 두 키로 BidEvaluation[]를 담는다.

get_bid_change_history

입찰공고번호로 공고의 변경이력(정정·변경 항목, 변경 전/후 값)을 조회한다. 변경이력은 물품·공사·용역 3구분만 존재한다(외자·기타 없음). 변경 이력이 없는 공고는 빈 결과를 반환한다.

반환: { bidNtceNo, anySucceeded, results }. results는 업무구분별 BidChange[]를 담는다.

get_bid_eligibility

입찰공고번호와 공고차수로 면허제한과 참가가능지역을 조회한다. 면허제한·참가가능지역은 공고차수 단위로 갈리므로 bidNtceOrd를 정확히 넘겨야 한다.

반환: { bidNtceNo, bidNtceOrd, anySucceeded, results }. results는 licenseLimit(면허제한)과 region(참가가능지역) 두 키로 BidEligibility[]를 담는다.

get_bid_items

입찰공고번호와 공고차수로 구매대상물품(품명·수량·단가·납품장소 등)을 조회한다. 구매대상물품은 물품·용역·외자 3구분만 존재한다(공사 없음).

반환: { bidNtceNo, bidNtceOrd, anySucceeded, results }. results는 업무구분별 BidItem[]를 담는다.

get_bid_attachments

입찰공고번호로 그 공고의 첨부파일 파일명·URL을 조회한다. 공고 본문 규격첨부(공고문·규격서·제안요청서·과업지시서 등)를 주 소스로, e발주·혁신장터 최종제안요청서(RFP) 첨부를 함께 반환한다. 파일 자체는 내려받지 않고 URL만 반환한다. 파일을 내려받아 목록을 얻으려면 download_attachments, 본문을 읽으려면 read_attachment를 쓴다.

반환: { bidNtceNo, anySucceeded, results }. results는 notice(공고 규격첨부)·eorder(e발주)·innovationRfp(혁신장터 RFP) 세 키로 BidAttachment[]를 담는다.

download_attachments

공고 첨부를 전부 디스크에 내려받고 ZIP은 풀어(원본 ZIP은 삭제), 읽을 수 있는 **파일 목록(카탈로그)**을 반환한다(본문 텍스트는 담지 않는다). 개별 파일 본문은 이 목록의 index를 read_attachment에 줘서 읽는다. get_bid_attachments가 URL만 돌려주는 데 반해, 이 도구는 실제 파일을 확보하고 목록을 만든다.

[!IMPORTANT] 이 도구는 읽기 전용이 아니다(readOnlyHint: false). 첨부를 <저장 디렉터리>/<공고번호>/ 아래에 평탄하게(ZIP 내부 파일도 같은 폴더로 풀어) 저장하고, 목록을 그 폴더의 .attachments-manifest.json에 남긴다. 저장 위치는 DATA_GO_KR_DOWNLOAD_DIR(미설정 시 ~/Downloads)로 정한다. 이미 만든 목록·파일은 재사용한다(전 첨부를 한 번 내려받아야 목록의 index가 생기므로, 파일 하나만 읽으려 해도 첫 호출은 전체를 받는다). 첨부가 나중에 바뀌면 refresh: true로 다시 호출해 새로 받는다.

ZIP은 목록에서 사라지고 내부 파일이 항목으로 펼쳐지며 container에 원본 ZIP명이 담긴다(중첩 ZIP은 재귀하지 않고 파일로만 남긴다). 각 항목의 extractable: true면 read_attachment로 본문(HWPX·구형 HWP·구형 DOC)을 읽을 수 있고, false(PDF·이미지 등)면 파일만 저장돼 있으니 savedPath로 직접 연다.

반환: { bidNtceNo, anySucceeded, resolveErrors?, files, truncatedFileList? }. files는 파일 카탈로그로, 각 항목은 index·fileNm·container?(담고 있던 ZIP명)·format(hwpx/hwp/doc/other)·extractable·byteSize·savedPath·note?(미해제 사유 등)를 담는다. resolveErrors는 첨부 소스(notice·eorder·innovationRfp)별 조회 실패 메시지, truncatedFileList: true는 파일 수가 상한(50)을 넘어 목록이 잘렸다는 신호다(본문 잘림을 뜻하는 read_attachment의 truncated와 다르다).

read_attachment

download_attachments가 준 파일 목록에서 index로 파일 하나를 골라 본문 텍스트를 읽는다. HWPX·구형 HWP·구형 DOC를 추출하며(그 외 format은 extractable: false라 본문이 비고 savedPath로 직접 열어야 한다) ZIP 내부 파일도 index로 직접 읽는다(container에 원본 ZIP명). 이미 내려받은 파일은 디스크에서 재사용하고, 목록이 아직 없으면 자동으로 먼저 내려받는다.

[!IMPORTANT] 이 도구도 목록이 없으면 첨부를 내려받으므로 읽기 전용이 아니다(readOnlyHint: false).

반환: { bidNtceNo, index, fileNm, container?, format, extractStatus, extractError?, byteSize, savedPath, text, textLength, truncated }. extractStatus는 full(본문 전량)/preview(구형 HWP 등에서 미리보기 텍스트만 추출)/unsupported(추출 대상 아님)/error(추출 실패). truncated: true는 본문의 다음 구간이 남았다는 신호다.

응답 필드

아래 각 타입은 조회 키인 bidNtceNo(공고번호)·bidNtceOrd(공고차수, 있는 경우)를 함께 포함한다.

BidNotice

bidNtceNm(공고명), ntceInsttNm(공고기관), dminsttNm(수요기관), bidNtceDt(공고일시), bidClseDt(마감일시), opengDt(개찰일시), presmptPrce(추정가격), bidNtceDtlUrl(상세 URL), bidMethdNm(입찰방법), cntrctCnclsMthdNm(계약체결방법), bidPrtcptLmtYn(투찰제한여부), prtcptLmtRgnNm(참가제한지역), cmmnSpldmdMethdNm(공동수급방식).

BidBasisAmount

bssamt(기초금액), evlBssAmt(평가기준금액), rsrvtnPrceRngBgnRate(예비가격범위율 하한), rsrvtnPrceRngEndRate(예비가격범위율 상한), bssamtOpenDt(기초금액 개찰일시).

BidEvaluation

prearngPrceDcsnMthdNm(예정가격결정방법), bidPrceCalclAOpenDt(산식A 개찰일시), npnInsrprm(국민연금보험료), mrfnHealthInsrprm(건강보험료), qltyMngcst(품질관리비), sftyMngcst(안전관리비), sftyChckMngcst(안전점검비), tmpNm(평가주력분야명).

BidChange

chgDt(변경일시), chgItemNm(변경항목명), bfchgVal(변경전값), afchgVal(변경후값), chgDataDivNm(변경구분명).

BidEligibility

lcnsLmtNm(면허제한명), permsnIndstrytyList(허용업종목록), prtcptPsblRgnNm(참가가능지역명).

BidItem

prdctClsfcNoNm(품명), dtilPrdctClsfcNoNm(세부품명), qty(수량), unit(단위), uprc(단가), dlvrPlce(납품장소), dlvrTmlmtDt(납품기한).

BidAttachment

fileNm(파일명), fileUrl(파일URL), docDivNm(문서구분명).

개발

nvm use            # Node 24
pnpm install
pnpm test          # vitest
pnpm typecheck     # tsc --noEmit
pnpm build         # tsup, dist/ 생성

문제 해결

• 인증 오류(코드 30): Encoding 키를 넣으면 이중 인코딩으로 실패한다. Decoding(원본) 키를 쓴다. 서버가 시작 시 Encoding 키로 보이면 경고 로그를 남긴다.

• 결과코드 메시지: 트래픽 초과, 인증키 만료 등 data.go.kr 결과코드는 한국어 메시지로 정규화되어 반환된다.

• 도구 동작 점검: MCP inspector로 직접 호출해 볼 수 있다.

  npx @modelcontextprotocol/inspector npx -y @opendata-kr/narajangteo-bid-mcp
  

라이선스

MIT