@opendata-kr/narajangteo-opening-mcp

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

MCP 클라이언트에서 나라장터 낙찰정보(개찰결과·최종낙찰자·투찰업체별 순위·예비가격·유찰/재입찰)를 자연어로 검색하고 조회한다. 예를 들어 이렇게 물어볼 수 있다.

• "R25BK00965123 공고 개찰결과 보여줘. 낙찰자랑 투찰업체별 순위·금액."
• "인천 지역 물품 낙찰 결과 최근 것 검색해줘."
• "이 공고 유찰됐는지 확인해줘."

특징

• 4계열 데이터를 3개 도구로 노출: 낙찰자(A)·개찰진행(B)·예비가격상세(C)·투찰업체별(D) 오퍼레이션을 검색용 2개(search_awards·search_openings)와 단건 심층조회 1개(get_bid_result)로 묶어 사용성을 단순화했다.
• 4개 업무구분 병렬 검색: 공사/용역/물품/외자를 한 번에 조회한다. 업무구분 미지정 시 전 구분을 동시 검색한다.
• 넓은 기간 자동 분할: startDate/endDate 범위가 넓으면 내부에서 창 단위로 쪼개 순차 조회한다.
• 부분 실패 표면화: 일부 구분·집행 조회가 실패해도 나머지 결과를 반환하고, 실패는 오류 메시지로 드러낸다(조용한 누락 없음).
• 복합키 정합: get_bid_result는 공고번호+차수+분류+재입찰번호로 A/B/C/D를 조인해 집행 단위로 묶는다.
• data.go.kr 에러코드 한국어화: 인증키 만료, 트래픽 초과 등 결과코드를 조치 가능한 한국어 메시지로 정규화한다.
• 이중 인코딩 방어: Encoding 키를 잘못 넣으면 경고하고, 요청은 한 번만 인코딩한다.
• 타임아웃: API 호출에 타임아웃을 둔다.

준비물

• Node.js 24 이상 (.nvmrc = lts/krypton).
• data.go.kr 인증키:
  1. 공공데이터포털에서 나라장터 낙찰정보서비스(ScsbidInfoService)를 활용신청해 [승인]을 받는다. 인증키는 계정당 하나지만, 각 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-opening": {
      "command": "npx",
      "args": ["-y", "@opendata-kr/narajangteo-opening-mcp@latest"],
      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
    }
  }
}

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

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

클라이언트별 설정

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

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

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

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

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

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

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

copilot

/mcp add

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

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

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

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

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

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

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

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

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

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

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

{
  "context_servers": {
    "narajangteo-opening": {
      "command": { "path": "npx", "args": ["-y", "@opendata-kr/narajangteo-opening-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-opening-mcp@latest

발견성

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

환경변수

도구

3개 도구 모두 읽기 전용 조회다(readOnlyHint). 업무구분(bidKind) 배열: cnstwk(공사) servc(용역) thng(물품) frgcpt(외자). 미지정 시 전 구분 병렬 조회한다(API 요청이 구분 수만큼 배수 소모되니 아는 구분은 지정한다). startDate/endDate(YYYYMMDD)는 함께 지정하며, 넓은 범위는 내부에서 창 단위로 분할해 순차 조회한다.

search_awards

나라장터 낙찰 결과(최종낙찰자)를 공고명·기관·수요기관(코드)·지역·업종·추정가·사업자번호·기간으로 검색한다. "누가 얼마에 낙찰받았나", 경쟁사(사업자번호) 낙찰 이력, 되풀이 사업의 종단 조회에 쓴다. 낙찰자만 반환하며 그 업체가 참여했으나 진 입찰은 미포함이다. 특정 공고의 개찰·투찰업체·예비가 상세는 get_bid_result, 개찰 진행·유찰 발굴은 search_openings를 쓴다.

search_openings

나라장터 개찰결과 목록을 검색하고 진행상태(개찰완료/유찰/재입찰)로 필터한다. 유찰·재입찰 공고 발굴에 쓴다. status는 API 파라미터가 아니라 응답 기준 클라이언트 필터라 응답이 느리니 기관·업종·기간으로 좁혀 쓴다(truncated: true면 미완 스캔). 재입찰은 동일 공고 내 재입찰이며 재공고가 아니다(재공고는 입찰공고 서비스 소관). 최종낙찰자 검색은 search_awards, 단일 공고 상세는 get_bid_result를 쓴다.

개찰결과 조회는 응답이 느리다(라이브 기준 20행 0.6초, 50행 9초, 100행은 타임아웃). 페이지 크기를 작게 유지하고 검색조건을 좁혀 쓴다.

get_bid_result

입찰공고번호로 그 공고의 낙찰자·개찰진행·예비가격상세(사정률)·투찰업체별 순위/금액/점수를 복합키(공고번호+차수+분류+재입찰번호) 정합으로 단건 조회한다. 딜 사후분석·투찰가 참고에 쓴다. 다분류·다차수 공고는 집행 단위 배열로 분리한다. 낙찰방식은 추정이며(협상계약만 기술·가격 점수 제공, 적격심사는 금액·순위만), myBizno를 주면 자사 투찰행에 isOurs를 표시한다. 여러 공고를 조건으로 찾으려면 search_awards 또는 search_openings를 쓴다.

모든 도구의 반환은 search_awards/search_openings가 { query, results }(업무구분별로 { totalCount, invalidCount, items } 또는 실패 시 { error }), get_bid_result가 { bidNtceNo, executions, errors, invalidCount, notes }다. invalidCount는 응답 스키마 검증에서 탈락해 items에서 제외된 건수다. 0이 아니면 API 응답 필드가 예고 없이 바뀐 신호이므로 이슈로 알려주면 반영한다.

응답 필드

검색 도구(search_awards·search_openings)는 업무구분별 results 맵을 반환한다. 각 구분은 { totalCount(BeforeFilter), invalidCount, items, truncated, failedWindows } | { error }다. 기간을 지정하면 캘린더 월 경계로 나눈 창을 순차 조회하고, 일부 창이 실패해도 나머지 성공분을 반환하며 실패한 창은 failedWindows(창·사유)에 담아 부분 결과임을 드러낸다.

AwardResult (계열 A, 최종낙찰자)

bidNtceNo(입찰공고번호), bidNtceNm(공고명), participants(참가업체수), winner(낙찰자), winnerBizno(낙찰자 사업자번호), winnerCeo(낙찰자 대표자), awardAmount(낙찰금액), awardRate(낙찰률), realOpeningDt(실개찰일시), demandInstitution(수요기관), finalAwardDate(최종낙찰일자).

OpeningSummary (계열 B, 개찰진행)

bidNtceNo, bidNtceNm, openingDt(개찰일시), participants(참가업체수), progress(진행상태: 개찰완료/유찰/재입찰), topBidder(1위 업체 { name, bizno, ceo, amount, rate } 또는 null), reservePriceFileExists(예비가격 파일 존재 여부), noticeInstitution(공고기관), demandInstitution(수요기관), failReasonHint(유찰 시 참가업체수 기반 추정 사유, 선택).

PreparPriceDetail (계열 C, 예비가격상세·집행 단위 집약)

planPrice(예정가격), baseAmount(기초금액), saJeongRate(사정률, 숫자 또는 null), totalReserveCount(총 복수예가수), drawn(추첨번호), reserves(복수예가 배열: seq·basePlanPrice).

BidderDetail (계열 D, 투찰업체별)

rank(순위), name(업체명), bizno(사업자번호), ceo(대표자), amount(투찰금액), rate(투찰율), remark(비고), priceScore(가격점수), techScore(기술점수), techRawScore(기술평점), totalScore(합산점수), bidDt(투찰일시), isOurs(자사 여부, myBizno 일치 시 true).

개발

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

문제 해결

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

• 개찰결과 조회가 느리거나 타임아웃: search_openings는 응답이 무겁다. pageSize를 기본값(20) 이하로 유지하고 기관·업종·기간으로 조건을 좁힌다. truncated: true가 보이면 스캔이 끝나지 않은 것이다.

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

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

  Terminal

  Copy

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

라이선스

MIT