나라장터 사용자정보

@opendata-kr/narajangteo-corpinfo-mcp

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

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 https://ampcode.com/manual#mcp 의 안내를 따르고 위 config를 사용한다. CLI로도 추가할 수 있다:

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

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

Antigravity

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

{

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

Claude Code

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

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

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

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

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

Windows

~/.codex/config.toml에 cmd /c 래핑으로 추가한다:

[mcp_servers.narajangteo-corpinfo]

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

Command Code

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

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

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

Continue

Continue의 MCP 가이드 를 따른다. Continue는 mcpServers를 배열로 쓴다:

{

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

Copilot CLI

Copilot CLI를 시작한다:

copilot

MCP 서버 추가 대화를 연다:

/mcp add

다음 필드를 입력하고 CTRL+S로 저장한다:

• Server name: narajangteo-corpinfo
• Server Type: [1] Local
• Command: npx -y @opendata-kr/narajangteo-corpinfo-mcp@latest
• Environment variables: DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키

Copilot / VS Code

버튼으로 설치:

버튼은 키를 담지 못한다. 설치 후 .vscode/mcp.json(또는 사용자 설정)의 env에 DATA_GO_KR_SERVICE_KEY를 추가한다.

직접 추가:

VS Code MCP 설정 가이드를 따르거나 CLI를 쓴다.

macOS·Linux:

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

Windows(PowerShell):

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

Cursor

버튼으로 설치:

버튼은 키를 담지 못한다. 설치 후 Cursor의 MCP 설정에서 env에 DATA_GO_KR_SERVICE_KEY를 추가한다.

직접 추가:

Cursor Settings → MCP → New MCP Server에서 위 config를 사용한다.

Factory CLI

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

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

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

Gemini CLI

Gemini CLI로 서버를 추가한다.

프로젝트 범위:

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

또는 MCP 가이드 를 따르고 위 config를 쓴다. ~/.gemini/settings.json의 서버 정의 env에 DATA_GO_KR_SERVICE_KEY를 추가한다.

Gemini Code Assist MCP 설정 가이드 를 따르고 위 config를 사용한다.

Grok Build CLI

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

이후 생성된 설정의 env(또는 셸 환경변수)에 DATA_GO_KR_SERVICE_KEY를 추가한다. 더 많은 옵션은 문서 참고.

JetBrains AI Assistant & Junie

Settings | Tools | AI Assistant | Model Context Protocol (MCP) → Add에서 위 config를 사용한다. Junie도 같은 방식으로 Settings | Tools | Junie | MCP Settings → Add에서 위 config를 사용한다.

Katalon Studio

Katalon StudioAssist는 MCP 프록시를 통해 stdio 서버를 연결한다.

1단계: MCP 프록시 설정 가이드 로 프록시를 설치한다.

2단계: 프록시로 서버를 띄운다(같은 셸에 DATA_GO_KR_SERVICE_KEY를 export 한 상태):

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

3단계: StudioAssist에 다음 설정으로 서버를 추가한다:

• Connection URL: http://127.0.0.1:8080/mcp
• Transport type: HTTP

Kiro

Kiro Settings에서 Configure MCP → Open Workspace or User MCP Config → 위 config를 사용한다.

또는 Activity Bar → Kiro → MCP Servers → Open MCP Config에서 위 config를 사용한다.

Mistral Vibe

~/.vibe/config.toml에 추가한다:

[[mcp_servers]]

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

OpenCode

opencode.json에 추가한다. 없으면 ~/.config/opencode/opencode.json에 만든다 ( 가이드 ):

{

"$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_키" } } } }

Qoder

Qoder Settings에서 MCP Server → + Add → 위 config를 사용한다.

또는 MCP 가이드 를 따르고 위 config를 쓴다.

Qoder CLI

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

프로젝트 범위:

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

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

Visual Studio

버튼으로 설치:

버튼은 키를 담지 못한다. 설치 후 서버 설정의 env에 DATA_GO_KR_SERVICE_KEY를 추가한다.