나라장터 사용자정보

@opendata-kr/narajangteo-corpinfo-mcp

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

[npm version] [CI] [node] [license]

Claude Desktop 등 MCP 클라이언트에서 사업자번호 하나로 조달업체의 자격과 프로파일을 자연어로 조회한다. 예를 들어 이렇게 물어볼 수 있다.

• "사업자번호 1234567890 업체 프로파일을 보여줘"
• "이 업체가 업종코드 1468 자격이 유효한지 확인해줘"
• "경쟁사 사업자번호 8888888888이 세부품명 8111159901 공급 자격이 있는지 봐줘"
• "이 업체에 유효한 부정당 제재가 있는지 확인해줘"

특징

• 사업자번호 하나로 4-facet 병렬 프로파일: 기본정보·등록업종·공급물품·부정당제재를 한 번에 조회한다.
• 업종 유효 판정: 코드가 목록에 있는지(보유)와 유효한지(유효)를 나눠 판정한다. 업종상태·유효기간을 반영하므로 코드 존재가 곧 유효를 뜻하지 않는다.
• 자사·경쟁사 구분 없는 조회: 공개 데이터라 사업자번호만 있으면 어느 업체든 조회한다.
• 부분 실패·조회상한 표면화: 일부 facet 조회가 실패해도 나머지 결과를 반환하고, 실패한 facet은 오류로 드러낸다. 목록이 조회 상한에 잘리면 truncated로 알려, 목록 부재를 미보유로 오판하지 않게 한다(조용한 거짓 음성 없음).
• data.go.kr 에러코드 한국어화: 인증키 만료, 트래픽 초과 등 결과코드를 조치 가능한 한국어 메시지로 정규화한다.
• 이중 인코딩 방어: Encoding 키를 잘못 넣으면 경고하고, 요청은 한 번만 인코딩한다.

준비물

• 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-corpinfo": {      "command": "npx",      "args": ["-y", "@opendata-kr/narajangteo-corpinfo-mcp@latest"],      "env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }    }  }}

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

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

클라이언트별 설정

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

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

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

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

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

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

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

copilot

/mcp add

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

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

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

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

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

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

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

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

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

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

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

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

발견성

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

환경변수

도구

2개 도구 모두 읽기 전용 조회다(readOnlyHint·openWorldHint). 사업자번호로 조회하며 업체명→사업자번호 리졸버나 코드→업체 역검색은 이 API 표면에 없어 지원하지 않는다. 등록업종·공급물품 목록은 조회 상한에 잘릴 수 있고, 잘리면 응답의 truncated가 true가 되며 notes에 경고가 실린다. 응답의 invalidCounts는 facet별로 응답 스키마 검증에서 탈락해 목록에서 제외된 건수다. 0이 아니면 API 응답 필드가 예고 없이 바뀐 신호이므로 이슈로 알려주면 반영한다. 한 호출이 facet 수만큼 API 요청을 소모한다(프로파일 4건·자격 판정 3건 이상).

get_company_profile

사업자등록번호로 한 조달업체의 기본정보·업종·공급물품·부정당제재를 한 번에 조립해 반환한다. 업체 전반을 훑을 때 쓴다. 특정 업종·품목 보유 여부만 판정하려면 check_company_qualification을 쓴다.

반환

각 facet(basic·industries·supplyProducts·sanctions)은 조회 실패 시 { error }로 격리된다(전체 실패로 뭉개지 않음).

check_company_qualification

사업자등록번호에 대해 지정 업종코드·세부품명번호의 보유·유효 여부와 부정당제재를 판정한다. 특정 입찰 자격 충족 여부를 볼 때 쓴다. 업체 전반 프로파일이 필요하면 get_company_profile을 쓴다.

반환

지정 코드가 목록에 없으면 held: false다. 다만 그 목록이 조회 상한에 잘렸으면(truncated) 미보유가 확정이 아님을 notes가 알린다.

응답 필드

CompanyBasic

CompanyIndustry

CompanySupplyProduct

CompanySanction

조회시점 유효한 제재분만 반환한다(만료·해제분 미포함).

IndustryCheck

check_company_qualification의 코드별 업종 판정.

ProductCheck

check_company_qualification의 코드별 세부품명 판정. 공급물품은 유효 개념이 없어 valid가 없다.

개발

nvm use            # Node 24pnpm installpnpm test          # vitestpnpm typecheck     # tsc --noEmitpnpm build         # tsup, dist/ 생성

문제 해결

• 인증 오류(코드 30): Encoding 키를 넣으면 이중 인코딩으로 실패한다. Decoding(원본) 키를 쓴다. 서버가 시작 시 Encoding 키로 보이면 경고 로그를 남긴다. 활용신청이 아직 [승인]되지 않은 경우에도 같은 오류가 나므로, 공공데이터포털 마이페이지에서 나라장터 사용자정보서비스 승인 상태를 확인한다.

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

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

  bash

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

라이선스

MIT