关于 나라장터 사전규격
这是将 data.go.kr 나라장터 预先规格信息 Open API 封装为本地 MCP 服务的工具,适合关注招标公告发布前规格公开阶段的采购人员和供应商。它提供按日期、机构、品目及组合条件检索的工具,并可查询规格意见与答复。
主要功能
- 01按日期或登记编号搜索预先规格
- 02按采购机构或需求机构筛选
- 03按品名和品目编号检索
- 04组合多项条件查询
- 05查看规格意见及答复
适用场景
- 01查找近期公开的预先规格
- 02跟踪特定机构的计划采购
- 03查找相关品目的规格公开信息
- 04查看某条规格的意见和回复
MCP 相关
本地 MCP 服务向 MCP 客户端提供五个只读工具,用于搜索预先规格、按机构或品目筛选、组合查询及获取规格意见。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
5收录的工具列表 · 更新于 3 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| kind | array | 否 | 业务类别:cnstwk=工程,servc=服务,thng=货物,frgcpt=外国货物。未指定时会并行查询所有类别,消耗 4 次 API 请求。如果知道业务类别,请指定以节省认证密钥的每日流量。 |
| page | integer | 否 | 页码(默认值:1) |
| endDate | string | 否 | 查询结束日期 YYYYMMDD |
| dateType | enum | 否 | 日期范围依据:regist=登记日期时间(默认),change=变更日期时间regist | change |
| pageSize | integer | 否 | 每页条数(默认值:10) |
| startDate | string | 否 | 查询开始日期 YYYYMMDD |
| specRegistNo | string | 否 | 按预先规格登记编号查询单条记录(指定时优先于日期范围) |
详细介绍
@opendata-kr/narajangteo-prespec-mcp
나라장터 사전규격정보서비스(공공데이터포털 data.go.kr) Open API를 감싼 로컬 MCP 서버.
MCP 클라이언트에서 나라장터 사전규격(발주기관이 입찰공고 전에 규격서를 사전공개하고 의견을 받는 단계)을 자연어로 검색하고 조회한다. 예를 들어 이렇게 물어볼 수 있다.
- "이번 달 올라온 물품 사전규격을 찾아줘"
- "해군군수사령부가 발주한 사전규격을 검색해줘"
- "사전규격등록번호 R26BD00234692의 규격서 의견을 보여줘"
특징
- 20개 오퍼레이션을 5개 도구로 노출: 전체 조회/기관별/품목별/복합검색/규격서의견 유형별로 묶어 사용성을 단순화했다.
- 4개 업무구분 병렬 검색: 공사/용역/물품/외자를 한 번에 조회한다. 업무구분 미지정 시 전 구분을 동시 검색한다.
- 부분 실패 표면화: 일부 구분 조회가 실패해도 나머지 결과를 반환하고, 실패한 구분은 오류 메시지로 드러낸다(조용한 누락 없음).
- data.go.kr 에러코드 한국어화: 인증키 만료, 트래픽 초과 등 결과코드를 조치 가능한 한국어 메시지로 정규화한다.
- 이중 인코딩 방어: Encoding 키를 잘못 넣으면 경고하고, 요청은 한 번만 인코딩한다.
- 타임아웃: API 호출에 타임아웃을 둔다.
준비물
- 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-prespec": {
"command": "npx",
"args": ["-y", "@opendata-kr/narajangteo-prespec-mcp@latest"],
"env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
}
}
}
说明
@opendata-kr/narajangteo-prespec-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-prespec -- npx -y @opendata-kr/narajangteo-prespec-mcp@latest
이후 생성된 설정의 env(또는 셸 환경변수)에 DATA_GO_KR_SERVICE_KEY를 추가한다.
Antigravity
Antigravity 문서의 커스텀 MCP 서버 추가 방법을 따라 아래 config를 MCP servers 설정에 넣는다:
{
"mcpServers": {
"narajangteo-prespec": {
"command": "npx",
"args": ["-y", "@opendata-kr/narajangteo-prespec-mcp@latest"],
"env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
}
}
}
Claude Code
Claude Code CLI로 서버를 추가한다 (가이드):
claude mcp add narajangteo-prespec --scope user --env DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 -- npx -y @opendata-kr/narajangteo-prespec-mcp@latest
Cline
https://docs.cline.bot/mcp/configuring-mcp-servers 의 안내를 따르고 위 config를 사용한다.Codex
MCP 설정 가이드를 따르고 위 config를 사용한다. Codex CLI로도 추가할 수 있다:codex mcp add narajangteo-prespec --env DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 -- npx -y @opendata-kr/narajangteo-prespec-mcp@latest
Windows
~/.codex/config.toml에 cmd /c 래핑으로 추가한다:
[mcp_servers.narajangteo-prespec]
command = "cmd"
args = ["/c", "npx", "-y", "@opendata-kr/narajangteo-prespec-mcp@latest"]
env = { DATA_GO_KR_SERVICE_KEY = "발급받은_Decoding_키" }
Command Code
Command Code CLI로 서버를 추가한다 (MCP 가이드):
cmd mcp add narajangteo-prespec --scope user npx -y @opendata-kr/narajangteo-prespec-mcp@latest
이후 생성된 설정의 env(또는 셸 환경변수)에 DATA_GO_KR_SERVICE_KEY를 추가한다.
Continue
Continue의 MCP 가이드를 따른다. Continue는 mcpServers를 배열로 쓴다:
{
"mcpServers": [
{
"name": "narajangteo-prespec",
"command": "npx",
"args": ["-y", "@opendata-kr/narajangteo-prespec-mcp@latest"],
"env": { "DATA_GO_KR_SERVICE_KEY": "발급받은_Decoding_키" }
}
]
}
Copilot CLI
Copilot CLI를 시작한다:
copilot
MCP 서버 추가 대화를 연다:
/mcp add
다음 필드를 입력하고 CTRL+S로 저장한다:
- Server name:
narajangteo-prespec - Server Type:
[1] Local - Command:
npx -y @opendata-kr/narajangteo-prespec-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-prespec","command":"npx","args":["-y","@opendata-kr/narajangteo-prespec-mcp@latest"],"env":{"DATA_GO_KR_SERVICE_KEY":"발급받은_Decoding_키"}}'
Windows(PowerShell):
code --add-mcp '{"""name""":"""narajangteo-prespec""","""command""":"""npx""","""args""":["""-y""","""@opendata-kr/narajangteo-prespec-mcp@latest"""],"""env""":{"""DATA_GO_KR_SERVICE_KEY""":"""발급받은_Decoding_키"""}}'
Cursor
通过按钮安装:
按钮无法包含密钥。安装后,在 Cursor 的 MCP 设置中将
DATA_GO_KR_SERVICE_KEY添加到env。
手动添加:
在 Cursor Settings → MCP → New MCP Server 中使用上面的 config。
Factory CLI
使用 Factory CLI 添加服务(指南):
droid mcp add narajangteo-prespec "npx -y @opendata-kr/narajangteo-prespec-mcp@latest"
之后,在生成的设置中的 env(或 Shell 环境变量)中添加 DATA_GO_KR_SERVICE_KEY。
Gemini CLI
使用 Gemini CLI 添加服务。
项目范围:
gemini mcp add narajangteo-prespec npx -y @opendata-kr/narajangteo-prespec-mcp@latest
全局:
gemini mcp add -s user narajangteo-prespec npx -y @opendata-kr/narajangteo-prespec-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-prespec npx -y @opendata-kr/narajangteo-prespec-mcp@latest
之后,在生成的设置中的 env(或 Shell 环境变量)中添加 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 步: 使用代理启动服务(在同一个 Shell 中导出 DATA_GO_KR_SERVICE_KEY):
DATA_GO_KR_SERVICE_KEY=발급받은_Decoding_키 mcp-proxy --transport streamablehttp --port 8080 -- npx -y @opendata-kr/narajangteo-prespec-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-prespec"
transport = "stdio"
command = "npx"
args = ["-y", "@opendata-kr/narajangteo-prespec-mcp@latest"]
env = { DATA_GO_KR_SERVICE_KEY = "발급받은_Decoding_키" }
OpenCode
添加到 opencode.json。如果文件不存在,则在 ~/.config/opencode/opencode.json 中创建(指南):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"narajangteo-prespec": {
"type": "local",
"command": ["npx", "-y", "@opendata-kr/narajangteo-prespec-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-prespec -- npx @opendata-kr/narajangteo-prespec-mcp@latest
全局:
qodercli mcp add -s user narajangteo-prespec -- npx @opendata-kr/narajangteo-prespec-mcp@latest
然后在生成的配置的 env(或 Shell 环境变量)中添加 DATA_GO_KR_SERVICE_KEY。
Warp
在 Settings | AI | Manage MCP Servers → + Add 中添加 MCP 服务,并使用上述 config。
Windsurf
按照 MCP 配置指南操作,并使用上述 config。Windsurf 使用 `mcpServers` 键(`~/.codeium/windsurf/mcp_config.json`)。Zed
添加到 ~/.config/zed/settings.json(架构可能因 Zed 版本而异,请查阅 Zed 官方文档):
{
"context_servers": {
"narajangteo-prespec": {
"command": { "path": "npx", "args": ["-y", "@opendata-kr/narajangteo-prespec-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-prespec-mcp@latest
将 http://127.0.0.1:8080/mcp 暴露为公开 HTTPS 端点由用户自行负责。(mcp-remote 用于将 stdio 客户端连接到远程服务,因此不适用于此处。)
发现方式
此服务在 MCP 注册表中的标识为 io.github.opendata-kr/narajangteo-prespec-mcp。可以在支持 registry.modelcontextprotocol.io 的客户端中搜索并安装。
环境变量
| 环境变量 | 必需 | 保密 | 默认值 | 说明 |
|---|---|---|---|---|
DATA_GO_KR_SERVICE_KEY | 是 | 是 | (无) | 公共数据门户的 **Decoding(原始)**认证密钥 |
DATA_GO_KR_BASE_URL | 否 | 否 | https://apis.data.go.kr/1230000/ao/HrcspSsstndrdInfoService | 包含服务路径的完整 URL 覆盖值 |
工具
全部 5 个工具都用于只读查询。20 个操作按查询方式分组。以下参数适用于所有工具。
kind:string[]。业务类型数组:cnstwk(工程)servc(服务)thng(物品)frgcpt(外资)。未指定时并行查询所有类型。并行查询会消耗 4 次 API 请求,因此已知业务类型时请指定page:number。页码(默认值为 1)pageSize:number。每页条数(默认值为 10,最大值为 100)
search_prespecs
按日期范围(登记/变更日期时间)或事前规格登记编号查询事前规格。用于简单的日期范围或编号查询。
| 参数 | 类型 | 说明 |
|---|---|---|
startDate | string | 查询开始日期 YYYYMMDD |
endDate | string | 查询结束日期 YYYYMMDD |
dateType | string | 日期范围依据:regist(登记日期时间,默认值)change(变更日期时间) |
specRegistNo | string | 按事前规格登记编号查询单条记录(指定时优先于日期范围) |
search_prespecs_by_institution
按订购机构名称或实际需求机构名称查询事前规格。用于查看特定机构计划订购的项目。
| 参数 | 类型 | 说明 |
|---|---|---|
orderInstitution | string | 订购机构名称 |
demandInstitution | string | 实际需求机构名称 |
startDate | string | 查询开始日期 YYYYMMDD |
endDate | string | 查询结束日期 YYYYMMDD |
search_prespecs_by_product
按商品名称或详细商品名称(编号)查询事前规格。用于查找关注商品的事前规格。
| 参数 | 类型 | 说明 |
|---|---|---|
productName | string | 商品名称(项目名称) |
detailProductCode | string | 详细商品名称编号 |
detailProductName | string | 详细商品名称 |
startDate | string | 查询开始日期 YYYYMMDD |
endDate | string | 查询结束日期 YYYYMMDD |
search_prespecs_advanced
발주기관·수요기관·품명·참조번호·SW사업여부 등 복합 조건으로 사전규격을 조회한다. 여러 필터를 동시에 걸 때 쓴다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
startDate | string | 접수 시작일 YYYYMMDD |
endDate | string | 접수 종료일 YYYYMMDD |
specRegistNo | string | 사전규격등록번호로 조회(지정 시 최우선) |
refNo | string | 참조번호로 조회(지정 시 기간보다 우선) |
noticeInstitution | string | 발주기관명 |
demandInstitution | string | 수요기관명 |
productName | string | 품명(사업명) |
detailProductCode | string | 세부품명번호 |
swBusinessYn | string | SW사업 여부(Y/N) |
조회 우선순위는 사전규격등록번호 > 참조번호 > 접수일시 순이다. 세부품명(
detailProductName) 검색은 이 API가 지원하지 않는다. 세부품명으로 찾으려면search_prespecs_by_product를 쓴다.
get_prespec_opinions
특정 사전규격(사전규격등록번호)에 달린 규격서 의견·답변 목록을 조회한다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
specRegistNo | string | 사전규격등록번호 |
startDate | string | 조회 시작일 YYYYMMDD |
endDate | string | 조회 종료일 YYYYMMDD |
모든 도구의 반환은 { query, results }다. results는 업무구분별로 { totalCount, invalidCount, items }를, 실패 시 해당 구분에 { error }를 담는다. invalidCount는 응답 스키마 검증에서 탈락해 items에서 제외된 건수다. 0이 아니면 API 응답 필드가 예고 없이 바뀐 신호이므로 이슈로 알려주면 반영한다.
응답 필드
Prespec (①②③④ 공통)
specRegistNo(사전규격등록번호), productName(품명/사업명), assignedBudget(배정예산액), orderInstitution(발주기관), demandInstitution(실수요기관), registDt(등록일시), changeDt(변경일시), opinionCloseDt(의견등록마감), receiptDt(접수일시), refNo(참조번호), bidNoticeList(관련 입찰공고번호 목록), businessDivision(업무구분), deliveryDays(납품기한일수), deliveryDeadline(납품기한), officialName(담당자), officialTel(담당자 전화), swBusinessYn(SW사업 여부), productDetailList(세부품목 배열: itemSeq·detailProductNo·detailProductName. 공사·용역은 빈 배열).
PrespecOpinion (⑤)
specRegistNo, refNo, opinionNo(의견번호), replyNo(답변번호), opinionTitle(제목), opinionContent(내용), writerCorp(작성업체), writerName(작성자), inputDt(등록일시), writerTel, writerEmail, opinionFileUrls(첨부파일 URL 배열).
개발
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-prespec-mcp
라이선스
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。