나라장터 사용자정보 について
公共データポータルの나라장터ユーザー情報 APIを使うローカル MCP サーバーです。事業者番号から企業情報を取得し、業種や商品に関する資格と業種登録の有効性を確認できます。
主な機能
- 01企業情報の4項目をまとめて取得
- 02業種コードの有効性を判定
- 03供給商品の資格を確認
- 04一部の照会失敗後も結果を返却
- 05一覧の切り捨てと API エラーを表示
活用シーン
- 01調達企業の全体プロフィールを確認
- 02入札に必要な業種資格を検証
- 03指定商品の供給資格を確認
- 04企業の不正業者制裁記録を調査
MCP 対応
企業プロフィールと資格判定の読み取り専用ツールを提供するローカル MCP サーバーです。data.go.kr の Decoding サービスキーが必要です。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
npx -y @opendata-kr/narajangteo-corpinfo-mcpDATA_GO_KR_SERVICE_KEYシークレット공공데이터포털 data.go.kr Decoding(원본) 인증키DATA_GO_KR_BASE_URL서비스 경로를 포함한 전체 base URL 오버라이드ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。
ツール
2掲載時のツール一覧 · 3 週間前に更新
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| bizno | string | はい | 10 桁の事業者登録番号(raw bizno) |
詳細
@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 인증키:
- 공공데이터포털에서 나라장터 사용자정보서비스를 활용신청해
[승인]을 받는다. 인증키는 계정당 하나지만, 각 API는 저마다 활용신청 승인이 있어야 그 API에서 인증된다. 서비스키가 있어도 이 API를 활용신청하지 않으면 인증 오류(코드 30)가 난다. - 마이페이지 → 활용신청 현황 → 개발계정 상세에서 Decoding 서비스키를 복사한다.
- 같은
DATA_GO_KR_SERVICE_KEY는 같은 계정으로 활용신청한 다른 data.go.kr API에도 재사용된다.
- 공공데이터포털에서 나라장터 사용자정보서비스를 활용신청해
ヒント
공공데이터포털이 처음이라면 활용신청부터 인증키 복사까지 그림으로 따라 하는 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_키" }
}
}
}
メモ
@opendata-kr/narajangteo-corpinfo-mcp@latest를 쓰면 클라이언트가 항상 최신 버전을 받는다.
重要
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로 저장한다:
- サーバー名:
narajangteo-corpinfo - サーバータイプ:
[1] Local - コマンド:
npx -y @opendata-kr/narajangteo-corpinfo-mcp@latest - 環境変数:
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に追加します:
- 接続URL:
http://127.0.0.1:8080/mcp - トランスポートタイプ:
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 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を追加します。
Warp
Settings | AI | Manage MCP Servers → + AddからMCP サーバーを追加し、上記の設定を使用します。
Windsurf
MCP 設定ガイドに従い、上記の設定を使用します。Windsurfでは`mcpServers`キーを使用します(`~/.codeium/windsurf/mcp_config.json`)。Zed
~/.config/zed/settings.jsonに追加します(スキーマはZedのバージョンによって異なる場合があるため、Zed公式ドキュメントを確認してください):
{
"context_servers": {
"narajangteo-corpinfo": {
"command": { "path": "npx", "args": ["-y", "@opendata-kr/narajangteo-corpinfo-mcp@latest"] },
"env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
}
}
}
ChatGPT · リモート専用クライアント
ChatGPT Developer Modeのように、リモート(HTTPS)MCPのみをサポートするクライアントは、ローカルのstdioサーバーに直接接続できません。stdio→HTTPブリッジ(mcp-proxy)を使ってこのサーバーをHTTPで起動し、公開HTTPSエンドポイント(リバースプロキシ・トンネル・ホスティング)経由で公開したうえで、そのURLをコネクターとして登録します。
DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 mcp-proxy --transport streamablehttp --port 8080 -- npx -y @opendata-kr/narajangteo-corpinfo-mcp@latest
http://127.0.0.1:8080/mcpを公開HTTPSとして公開するのはユーザー自身で行ってください。(mcp-remoteは反対に、stdioクライアントをリモートサーバーに接続するときに使うツールなので、ここでは適していません。)
検出可能性
このサーバーは、MCP レジストリにio.github.opendata-kr/narajangteo-corpinfoとして登録されています。registry.modelcontextprotocol.ioに対応したクライアントから検索・インストールできます。
環境変数
| 環境変数 | 必須 | 秘密 | デフォルト値 | 説明 |
|---|---|---|---|---|
DATA_GO_KR_SERVICE_KEY | はい | はい | (なし) | 公共データポータルの**Decoding(原本)**認証キー |
DATA_GO_KR_BASE_URL | いいえ | いいえ | https://apis.data.go.kr/1230000/ao/UsrInfoService02 | サービスパスを含む完全なURLのオーバーライド |
ツール
2つのツールはいずれも読み取り専用の照会です(readOnlyHint・openWorldHint)。事業者番号で照会します。事業者名から事業者番号へのリゾルバーや、コードから事業者名を逆引きする機能はこのAPIの範囲にないため、サポートしていません。登録業種・供給物品の一覧は照会上限によって切り捨てられる場合があります。切り捨てられた場合、応答のtruncatedがtrueになり、notesに警告が含まれます。応答のinvalidCountsは、ファセットごとに応答スキーマの検証に失敗し、一覧から除外された件数です。0以外の場合、API応答のフィールドが予告なく変更されたことを示すため、イシューでお知らせいただければ対応します。1回の呼び出しでファセット数分のAPIリクエストを消費します(プロファイルは4件、資格判定は3件以上)。
| ツール | 説明 |
|---|---|
get_company_profile | 事業者番号を使って、基本情報・登録業種・供給物品・不当業者制裁を一度に取得 |
check_company_qualification | 事業者番号について、指定された業種コード・詳細品目番号の保有状況と有効性を判定 |
get_company_profile
사업자등록번호로 한 조달업체의 기본정보·업종·공급물품·부정당제재를 한 번에 조립해 반환한다. 업체 전반을 훑을 때 쓴다. 특정 업종·품목 보유 여부만 판정하려면 check_company_qualification을 쓴다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
bizno | string | 사업자등록번호 10자리(숫자만). 필수 |
반환
| 필드 | 타입 | 설명 |
|---|---|---|
bizno | string | 조회한 사업자번호 |
basic | CompanyBasic | null | { error } | 기본정보. 미조회 시 null, 조회 실패 시 { error } |
industries | CompanyIndustry[] | { error } | 등록업종 목록 |
supplyProducts | CompanySupplyProduct[] | { error } | 공급물품 목록 |
sanctions | { sanctioned: boolean, records: CompanySanction[] } | { error } | 부정당제재 유무와 목록 |
truncated | { industries, supplyProducts, sanctions } (각 boolean) | facet별 목록 조회 상한 도달 여부 |
invalidCounts | { basic, industries, supplyProducts, sanctions } (각 number) | facet별 스키마 검증 탈락 건수 |
notes | string[] | 미등록·조회상한 등 주의사항 |
각 facet(basic·industries·supplyProducts·sanctions)은 조회 실패 시 { error }로 격리된다(전체 실패로 뭉개지 않음).
check_company_qualification
사업자등록번호에 대해 지정 업종코드·세부품명번호의 보유·유효 여부와 부정당제재를 판정한다. 특정 입찰 자격 충족 여부를 볼 때 쓴다. 업체 전반 프로파일이 필요하면 get_company_profile을 쓴다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
bizno | string | 사업자등록번호 10자리(숫자만). 필수 |
industryCodes | string[] | 업종코드 4자리 배열. 미지정 또는 빈 배열이면 보유 업종 전 목록 반환 |
productCodes | string[] | 세부품명번호 10자리 배열. 미지정 또는 빈 배열이면 공급물품 전 목록 반환 |
반환
| 필드 | 타입 | 설명 |
|---|---|---|
bizno | string | 조회한 사업자번호 |
industryChecks | IndustryCheck[] | { error } | 코드별 업종 보유·유효 판정 |
productChecks | ProductCheck[] | { error } | 코드별 세부품명 보유·제조 판정 |
sanction | { sanctioned: boolean, records: CompanySanction[] } | { error } | 부정당제재 유무와 목록 |
truncated | { industries, supplyProducts, sanctions } (각 boolean) | 목록 조회 상한 도달 여부 |
invalidCounts | { industries, supplyProducts, sanctions } (각 number) | facet별 스키마 검증 탈락 건수 |
notes | string[] | 역검색 불가·미보유 미확정 등 주의사항 |
지정 코드가 목록에 없으면 held: false다. 다만 그 목록이 조회 상한에 잘렸으면(truncated) 미보유가 확정이 아님을 notes가 알린다.
응답 필드
CompanyBasic
| 필드 | 설명 |
|---|---|
bizno | 사업자번호 |
corpNm | 업체명 |
engCorpNm | 영문업체명 |
ceoNm | 대표자명 |
opbizDt | 개업일시 |
rgnNm | 지역명 |
zip | 우편번호 |
adrs · dtlAdrs | 주소 · 상세주소 |
telNo · faxNo | 전화 · 팩스 |
hmpgAdrs | 홈페이지 |
mnfctDivNm | 제조구분명 |
emplyeNum | 종업원수 |
corpBsnsDivNm | 업체업무구분명 |
hdoffceDivNm | 본사구분명 |
CompanyIndustry
| 필드 | 타입 | 설명 |
|---|---|---|
indstrytyCd | string | 업종코드 4자리 |
indstrytyNm | string | 업종명 |
statusName | string | 업종상태명 |
expiryDate | string | 유효기간만료일시(빈값은 무기한) |
representative | string | 대표업종여부(Y/N) |
valid | boolean | 유효 판정 결과(상태·유효기간 반영) |
CompanySupplyProduct
| 필드 | 타입 | 설명 |
|---|---|---|
dtilPrdctClsfcNo | string | 세부품명번호 10자리 |
dtilPrdctClsfcNoNm | string | 세부품명 |
manufacture | boolean | 제조여부 |
rgstDt | string | 등록일시 |
CompanySanction
| 필드 | 설명 |
|---|---|
bizno | 사업자번호 |
corpNm | 업체명 |
sanctionBgnDt | 제재시작일자 |
sanctionEndDt | 제재종료일자 |
sanctionInstitution | 제재통보 수요기관명 |
legalBasis | 근거법령명 |
articleClause | 조항호 |
sanctionStatus | 제재상태명 |
조회시점 유효한 제재분만 반환한다(만료·해제분 미포함).
IndustryCheck
check_company_qualification의 코드별 업종 판정.
| 필드 | 타입 | 설명 |
|---|---|---|
code | string | 업종코드 |
held | boolean | 보유 여부 |
valid | boolean | 유효 여부 |
statusName | string | 업종상태명 |
expiryDate | string | 유효기간만료일시 |
representative | string | 대표업종여부 |
ProductCheck
check_company_qualification의 코드별 세부품명 판정. 공급물품은 유효 개념이 없어 valid가 없다.
| 필드 | 타입 | 설명 |
|---|---|---|
code | string | 세부품명번호 |
held | boolean | 보유 여부 |
manufacture | boolean | 제조여부 |
개발
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-corpinfo-mcp
라이선스
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。