mcpField
나
나라장터 사용자정보

나라장터 사용자정보

本地服务
github.com法律与政务015 周前更新

关于 나라장터 사용자정보

这是一个本地 MCP 服务,将公共数据门户的나라장터用户信息 API 提供给采购相关查询。输入 사업자번호 即可查看企业资料、登记行业、供应商品及不正当制裁,并判定指定代码的资格有效性。

主要功能

  1. 01并行汇总四类企业信息
  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 位企业注册号(原始 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

通过按钮安装:

将 narajangteo-corpinfo MCP 服务添加到 Cursor

按钮无法包含密钥。安装后,在 Cursor 的 MCP 设置中将 DATA_GO_KR_SERVICE_KEY 添加到 env。

手动添加:

在 Cursor Settings → MCP → New MCP Server 中使用上述配置。

Factory CLI

使用 Factory CLI 添加服务(指南):

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

之后,在生成的配置的 env 中(或在 shell 环境变量中)添加 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 指南操作,并使用上述配置。在 ~/.gemini/settings.json 的服务定义 env 中添加 DATA_GO_KR_SERVICE_KEY。

Gemini Code Assist 按照 MCP 设置指南操作,并使用上述配置。
Grok Build CLI
grok mcp add narajangteo-corpinfo npx -y @opendata-kr/narajangteo-corpinfo-mcp@latest

之后,在生成的配置的 env 中(或在 shell 环境变量中)添加 DATA_GO_KR_SERVICE_KEY。更多选项请参阅文档。

JetBrains AI Assistant & Junie

在 Settings | Tools | AI Assistant | Model Context Protocol (MCP) → Add 中使用上述配置。 Junie 也可通过相同方式,在 Settings | Tools | Junie | MCP Settings → Add 中使用上述配置。

Katalon Studio

Katalon StudioAssist 通过 MCP 代理连接 stdio 服务。

**第 1 步:**按照 MCP 代理设置指南安装代理。

**第 2 步:**通过代理启动服务(在同一 shell 中已 export DATA_GO_KR_SERVICE_KEY):

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,然后使用上述配置。

或者在 Activity Bar → Kiro → MCP Servers → Open MCP 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 中(或 shell 环境变量中)添加 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 表示各 facet 中因未通过响应架构验证而从列表中排除的条目数。若该值不为 0,说明 API 响应字段可能已在未通知的情况下发生变化;请通过提交问题告知,我们会予以处理。一次调用会消耗与 facet 数量相等的 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

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。