mcpField
나
나라장터 사용자정보

나라장터 사용자정보

ローカル
github.com法務・行政015 週間前に更新

나라장터 사용자정보 について

公共データポータルの나라장터ユーザー情報 APIを使うローカル MCP サーバーです。事業者番号から企業情報を取得し、業種や商品に関する資格と業種登録の有効性を確認できます。

主な機能

  1. 01企業情報の4項目をまとめて取得
  2. 02業種コードの有効性を判定
  3. 03供給商品の資格を確認
  4. 04一部の照会失敗後も結果を返却
  5. 05一覧の切り捨てと API エラーを表示

活用シーン

  1. 01調達企業の全体プロフィールを確認
  2. 02入札に必要な業種資格を検証
  3. 03指定商品の供給資格を確認
  4. 04企業の不正業者制裁記録を調査

MCP 対応

企業プロフィールと資格判定の読み取り専用ツールを提供するローカル MCP サーバーです。data.go.kr の Decoding サービスキーが必要です。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"opendata-kr-narajangteo-corpinfo": {
"command": "npx",
"args": [
"-y",
"@opendata-kr/narajangteo-corpinfo-mcp"
],
"env": {
"DATA_GO_KR_SERVICE_KEY": "<DATA_GO_KR_SERVICE_KEY>",
"DATA_GO_KR_BASE_URL": "<DATA_GO_KR_BASE_URL>"
}
}
}
}
起動コマンドnpx -y @opendata-kr/narajangteo-corpinfo-mcp
設定が必要な環境変数
DATA_GO_KR_SERVICE_KEYシークレット공공데이터포털 data.go.kr Decoding(원본) 인증키
DATA_GO_KR_BASE_URL서비스 경로를 포함한 전체 base URL 오버라이드

ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npm@opendata-kr/narajangteo-corpinfo-mcp0.2.0

ツール

2

掲載時のツール一覧 · 3 週間前に更新

パラメーター型必須説明
biznostringはい10 桁の事業者登録番号(raw bizno)

詳細

@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에도 재사용된다.

ヒント

공공데이터포털이 처음이라면 활용신청부터 인증키 복사까지 그림으로 따라 하는 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

ボタンでインストール:

VS Code にインストール

VS Code Insiders にインストール

ボタンではキーを設定できません。インストール後、.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 に narajangteo-corpinfo MCP サーバーを追加

ボタンではキーを設定できません。インストール後、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

Qoder SettingsでMCP Server → + Addを選択し、上記の設定を使用します。

または、MCP ガイドに従い、上記の設定を使用します。

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

ボタンでインストール:

Visual Studioにインストール

ボタンにはキーを含められません。インストール後、サーバー設定の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을 쓴다.

파라미터타입설명
biznostring사업자등록번호 10자리(숫자만). 필수

반환

필드타입설명
biznostring조회한 사업자번호
basicCompanyBasic | null | { error }기본정보. 미조회 시 null, 조회 실패 시 { error }
industriesCompanyIndustry[] | { error }등록업종 목록
supplyProductsCompanySupplyProduct[] | { error }공급물품 목록
sanctions{ sanctioned: boolean, records: CompanySanction[] } | { error }부정당제재 유무와 목록
truncated{ industries, supplyProducts, sanctions } (각 boolean)facet별 목록 조회 상한 도달 여부
invalidCounts{ basic, industries, supplyProducts, sanctions } (각 number)facet별 스키마 검증 탈락 건수
notesstring[]미등록·조회상한 등 주의사항

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

check_company_qualification

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

파라미터타입설명
biznostring사업자등록번호 10자리(숫자만). 필수
industryCodesstring[]업종코드 4자리 배열. 미지정 또는 빈 배열이면 보유 업종 전 목록 반환
productCodesstring[]세부품명번호 10자리 배열. 미지정 또는 빈 배열이면 공급물품 전 목록 반환

반환

필드타입설명
biznostring조회한 사업자번호
industryChecksIndustryCheck[] | { error }코드별 업종 보유·유효 판정
productChecksProductCheck[] | { error }코드별 세부품명 보유·제조 판정
sanction{ sanctioned: boolean, records: CompanySanction[] } | { error }부정당제재 유무와 목록
truncated{ industries, supplyProducts, sanctions } (각 boolean)목록 조회 상한 도달 여부
invalidCounts{ industries, supplyProducts, sanctions } (각 number)facet별 스키마 검증 탈락 건수
notesstring[]역검색 불가·미보유 미확정 등 주의사항

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

응답 필드

CompanyBasic
필드설명
bizno사업자번호
corpNm업체명
engCorpNm영문업체명
ceoNm대표자명
opbizDt개업일시
rgnNm지역명
zip우편번호
adrs · dtlAdrs주소 · 상세주소
telNo · faxNo전화 · 팩스
hmpgAdrs홈페이지
mnfctDivNm제조구분명
emplyeNum종업원수
corpBsnsDivNm업체업무구분명
hdoffceDivNm본사구분명
CompanyIndustry
필드타입설명
indstrytyCdstring업종코드 4자리
indstrytyNmstring업종명
statusNamestring업종상태명
expiryDatestring유효기간만료일시(빈값은 무기한)
representativestring대표업종여부(Y/N)
validboolean유효 판정 결과(상태·유효기간 반영)
CompanySupplyProduct
필드타입설명
dtilPrdctClsfcNostring세부품명번호 10자리
dtilPrdctClsfcNoNmstring세부품명
manufactureboolean제조여부
rgstDtstring등록일시
CompanySanction
필드설명
bizno사업자번호
corpNm업체명
sanctionBgnDt제재시작일자
sanctionEndDt제재종료일자
sanctionInstitution제재통보 수요기관명
legalBasis근거법령명
articleClause조항호
sanctionStatus제재상태명

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

IndustryCheck

check_company_qualification의 코드별 업종 판정.

필드타입설명
codestring업종코드
heldboolean보유 여부
validboolean유효 여부
statusNamestring업종상태명
expiryDatestring유효기간만료일시
representativestring대표업종여부
ProductCheck

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

필드타입설명
codestring세부품명번호
heldboolean보유 여부
manufactureboolean제조여부

개발

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
    

라이선스

MIT

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。