关于 나라장터 사용자정보
这是一个本地 MCP 服务,将公共数据门户的나라장터用户信息 API 提供给采购相关查询。输入 사업자번호 即可查看企业资料、登记行业、供应商品及不正当制裁,并判定指定代码的资格有效性。
主要功能
- 01并行汇总四类企业信息
- 02判定行业代码是否有效
- 03核查供应商品资格
- 04部分查询失败时保留结果
- 05标示列表截断和 API 错误
适用场景
- 01查看采购企业的完整资料
- 02核实企业是否具备指定行业资格
- 03检查企业是否供应特定商品
- 04查询企业的不正当制裁记录
MCP 相关
作为本地 MCP 服务,向客户端提供只读的企业资料查询和资格判定工具。需配置 data.go.kr 的 Decoding 服务密钥。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
2收录的工具列表 · 更新于 3 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| bizno | string | 是 | 10 位企业注册号(原始 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 设置中将
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 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。
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을 쓴다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
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 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。