korea-onegov-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@korea-onegov-mcp Search for press releases about renewable energy"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
korea-onegov-mcp
OneGov — 대한민국 중앙행정기관 약 50곳의 보도자료·정책·법령·통계·정보공개·고시공고 약 9만 건을 모아 색인한 통합검색 서비스 — 의 공개 API를 감싼 MCP 서버입니다.
사이트에 직접 들어가지 않고 Claude(웹/데스크톱/Code), ChatGPT(개발자 모드), Cursor 등에서 대화로 정부 자료를 검색·조회할 수 있습니다.
원격(Streamable HTTP) 과 로컬(stdio) 두 방식을 하나의 코드베이스로 지원합니다.
빌드 단계가 없습니다. 순수 ESM JavaScript라
git push하면 Vercel이 그대로 배포합니다.인증 키가 필요 없습니다. OneGov API가 무인증 공개 API이기 때문입니다.
⚠️ OneGov는 정부 공식 사이트가 아니라 공개자료를 모아 색인한 비공식 검색 서비스입니다. 자료 대부분에 공공누리(KOGL) 조건이 적용되므로, 인용·재사용할 때는 기관명과 원문 링크(source_url) 를 반드시 함께 표기하세요. 이 서버는 모든 응답 하단에 해당 안내를 자동으로 붙입니다.
제공 도구 (11개)
도구 | 하는 일 |
| 통합검색. 문서유형·기관·지역·법령·발행일 범위·정렬·검색모드 전체 필터 지원 |
| 문서 id로 전문 + 첨부 + 관련법령 + 연관문서 조회 |
| 실제 색인된 검색어 자동완성 (0건 나올 때 먼저 쓰기) |
| 기관코드 목록과 보유 문서 수 ( |
| 공개자료 제목에 자주 등장하는 상위 주제어 |
| 마감임박 지원사업 공고 (D-day·기관 필터) |
| 지원사업·공고 주제 검색 (범위를 미리 좁힌 편의 도구) |
| 특정 부처의 최근 N일 자료를 최신순으로 |
| 검색 → 상위 문서 본문 자동 수집까지 한 번에 (주제 브리핑) |
| ChatGPT 커넥터·딥리서치 규격 호환용 ( |
모든 도구는 읽기 전용이며, response_format 으로 markdown(기본) / json 을 고를 수 있습니다.
Related MCP server: korean-public-data-mcp
A. 원격 MCP 서버로 배포하기 (Claude 웹 / ChatGPT 웹에서 쓰려면 이 방법)
A-1. Vercel에 올리기
방법 1 — GitHub 경유 (권장)
이 폴더에는 이미 git 저장소가 초기화되어 있고 커밋도 들어 있습니다. 원격만 연결해서 밀어 올리면 됩니다.
윈도우 — 탐색기에서 push-to-github.cmd 를 더블클릭하거나, 명령 프롬프트에서:
push-to-github.cmdgit·GitHub CLI가 없으면 스크립트가 winget으로 설치할지 물어보고, GitHub 로그인까지 안내한 뒤 저장소 생성과 푸시를 진행합니다.
(윈도우 CMD에는 bash 가 없으므로 bash push-to-github.sh 는 동작하지 않습니다.)
macOS / Linux
cd korea-onegov-mcp
bash push-to-github.sh수동으로 하려면 — github.com/new 에서 빈 저장소(README·라이선스 체크 해제)를 만든 뒤:
git remote add origin https://github.com/<사용자명>/korea-onegov-mcp.git
git push -u origin main그다음 vercel.com/new 에서 해당 저장소를 Import 합니다.
3. Framework Preset은 Other, 나머지 설정은 손대지 않고 Deploy.
4. 배포가 끝나면 https://<프로젝트명>.vercel.app 주소가 나옵니다.
방법 2 — CLI
npm i -g vercel
cd korea-onegov-mcp
vercel --prodA-2. 배포 확인
curl https://<프로젝트명>.vercel.app/mcp
# {"server":"korea-onegov-mcp-server","version":"1.0.0", ...} 가 나오면 정상
# 도구 목록까지 확인
curl -X POST https://<프로젝트명>.vercel.app/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'MCP 접속 주소는 https://<프로젝트명>.vercel.app/mcp 입니다. (/api/mcp 도 동일하게 동작합니다.)
A-3. Claude 웹/데스크톱에 등록
Claude 설정 → Connectors
+ Add custom connector
이름:
OneGov 정부자료, URL:https://<프로젝트명>.vercel.app/mcpAdd → 대화창의 도구 아이콘에서 켜고 사용
인증 설정은 비워 두면 됩니다(무인증 서버).
A-4. ChatGPT에 등록
ChatGPT의 커스텀 MCP 커넥터는 개발자 모드가 필요하며 Pro/Team/Enterprise/Edu 플랜에서 제공됩니다.
설정 → Connectors → Advanced → Developer mode 켜기
Connectors → Create
이름과 서버 URL(
https://<프로젝트명>.vercel.app/mcp) 입력, 인증은 No authentication신뢰 확인에 체크하고 생성
이 서버는 딥리서치 규격에 맞춘 search / fetch 도구를 함께 제공하므로 딥리서치 커넥터로도 붙습니다.
B. 로컬(stdio)로 쓰기 — Claude 데스크톱앱 / Claude Code / Cursor
cd korea-onegov-mcp
npm install
node src/index.js --helpClaude 데스크톱앱
claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) 에 추가:
{
"mcpServers": {
"korea-onegov": {
"command": "node",
"args": ["/절대/경로/korea-onegov-mcp/src/index.js"]
}
}
}Claude Code
claude mcp add korea-onegov -- node /절대/경로/korea-onegov-mcp/src/index.js로컬 HTTP로 띄우기 (원격 배포 전 테스트용)
npm run http # http://127.0.0.1:3000/mcp
npm run inspect # MCP Inspector로 도구 직접 호출해 보기환경변수
이름 | 기본값 | 설명 |
|
| 로컬 HTTP 모드 포트 |
|
| 로컬 HTTP 모드 바인딩 주소 |
|
| OneGov API 베이스 URL |
|
| 외부 API 타임아웃 |
| (켜짐) |
|
테스트
npm run smoke # HTTP 모드로 띄우고 실제 API까지 20개 항목 검증
node scripts/stdio-test.js # stdio 모드 연결 + 주제 브리핑 도구 확인구조
korea-onegov-mcp/
├── api/mcp.js Vercel 서버리스 함수(원격 MCP 엔드포인트)
├── src/
│ ├── index.js 실행 진입점 (stdio / 로컬 HTTP)
│ ├── server.js McpServer 생성 + 사용 지침
│ ├── tools.js 도구 11개 정의
│ ├── client.js OneGov API 클라이언트 + 에러 매핑
│ ├── format.js 마크다운/JSON 포매팅, 길이 제한
│ └── constants.js 상수
├── scripts/ 스모크 테스트
├── public/index.html 배포 확인용 안내 페이지
└── vercel.json 함수 설정 + /mcp 리라이트알아 둘 점
레이트리밋: OneGov API는 IP 단위 제한이 있어 429가 날 수 있습니다. 서버는 429를 만나면 재시도 안내가 담긴 에러 메시지를 돌려줍니다.
응답 길이: 한 응답이 25,000자를 넘으면 잘라내고 "필터를 좁히라"는 안내를 붙입니다.
stateless: Vercel 함수는 요청마다 새 서버 인스턴스를 만드는 stateless Streamable HTTP 모드로 동작합니다. SSE(GET 스트리밍)는 지원하지 않습니다.
원본 서비스 존중: 이 래퍼는 OneGov가 공개한 API를 그대로 호출합니다. 대량 크롤링 용도로 쓰지 마세요.
라이선스
MIT (이 래퍼 코드에 한함). 검색되는 자료의 저작권·이용조건은 각 소관 기관 및 공공누리 조건을 따릅니다.
Available Tools
11 toolsfetchFetch (ChatGPT 호환)ARead-onlyIdempotent
ChatGPT 커넥터/딥리서치 규격에 맞춘 문서 조회 도구. search 가 돌려준 id로 전문을 가져온다.
Args: id (string, 필수) Returns: { id, title, text, url, metadata } 를 JSON 문자열로.
Inputs: id (required).
onegov_deadline_grants마감임박 지원사업 공고ARead-onlyIdempotent
접수 마감이 임박한 정부 지원사업·공고를 마감일 순으로 돌려준다. 창업·중소기업·소상공인 지원사업 탐색의 출발점.
Args:
max_dday (number, 0~60, 선택): D-day 상한. 예: 7 이면 일주일 안에 마감하는 것만.
org_contains (string, 선택): 기관명 부분 문자열 필터(예: "중소벤처기업부", "조달청").
limit (number, 1~100, 기본 30)
response_format ('markdown'|'json', 기본 markdown)
Returns: { grants: [{ id, title, org, ministry_name, deadline_at, dday, support_field, apply_target, region, startup_years, source_url, kogl_type }] } dday=0 은 오늘 마감이라는 뜻이다.
Examples:
"이번 주 마감인 지원사업" → max_dday=7
"중기부 지원사업 마감 임박" → org_contains="중소벤처기업부"
조건에 맞는 게 없으면 onegov_find_support_programs 로 넓게 검색할 것.
Inputs: limit, max_dday, org_contains, response_format.
onegov_find_support_programs지원사업·공고 찾기ARead-onlyIdempotent
지원사업(category=grant) 과 고시·공고(doc_type=notice) 로 범위를 미리 좁혀 검색하는 편의 도구. "창업 지원금", "소상공인 지원사업" 같은 요청에 바로 쓴다.
onegov_search 에 category=["grant"] 를 매번 넣는 것과 같지만, 필요한 필터만 노출해 실수를 줄인다.
Args:
query (string, 필수): 무엇에 대한 지원사업인지(예: "청년 창업", "수출", "AI").
region (string[], 선택): 지역명(예: ["서울특별시"]). 전국 사업은 "전국".
ministry (string[], 선택): 기관코드.
from / to (YYYY-MM-DD, 선택): 공고 발행일 범위.
include_notices (boolean, 기본 true): 지원사업 분류가 안 붙은 일반 고시·공고까지 함께 볼지 여부.
sort ('relevance'|'date_desc'|'date_asc', 기본 date_desc): 기본은 최신순.
page / size / response_format: onegov_search 와 동일.
Returns: onegov_search 와 동일한 형식.
Examples:
"요즘 나온 청년 창업 지원사업" → query="청년 창업"
"경기도 소상공인 지원" → query="소상공인", region=["경기도"]
마감일 기준으로 급한 것부터 보려면 onegov_deadline_grants 를 먼저 쓸 것.
Inputs: query (required), to, from, page, +6 more.
onegov_get_document문서 전문 조회ARead-onlyIdempotent
문서 id로 전문(본문)과 첨부·관련법령·연관문서를 가져온다. id는 onegov_search 결과의 id 필드(UUID)다.
Args:
id (string, 필수): 문서 UUID.
max_body_chars (number, 기본 8000, 최대 40000): 본문 최대 길이. 길면 잘리고 안내가 붙는다.
response_format ('markdown'|'json', 기본 markdown)
Returns: markdown: 제목 · 메타(기관/발행일/원문링크/공공누리 유형/관련법령) · 본문 · 첨부 · 연관 문서. json: { id, doc_type, title, summary, body, ministry_name, published_at, source_url, kogl_type, kogl_notice, attachments[], law_ref[], region, links{related_by_law[], same_ministry_recent[]} }
Examples:
검색 후 "이 공고 신청 자격 알려줘" → 해당 결과의 id로 호출
쓰지 말 것: 아직 문서를 특정하지 못했을 때(→ onegov_search 먼저)
Inputs: id (required), max_body_chars, response_format.
onegov_list_ministries기관(부처) 코드 목록ARead-onlyIdempotent
색인된 중앙행정기관 목록과 각 기관의 보유 문서 수를 돌려준다. onegov_search 의 ministry 필터에 넣을 코드를 여기서 얻는다.
Args:
name_contains (string, 선택): 기관명에 포함된 글자로 필터(예: "고용", "국토").
response_format ('markdown'|'json', 기본 markdown)
Returns: { ministries: [{ ministry_code, name, org_type, parent_code, doc_count }] } 참고: "_AGGREGATE"는 특정 부처가 아니라 K-Startup 등 집계 포털에서 모은 전 기관 공통 자료다(가장 문서가 많다).
Examples:
"국토교통부 코드가 뭐야" → name_contains="국토" → MOLIT
"어느 부처 자료가 제일 많아" → 전체 조회
Inputs: name_contains, response_format.
onegov_ministry_latest특정 부처 최신 자료ARead-onlyIdempotent
한 부처(또는 여러 부처)의 최신 공개자료를 발행일 역순으로 가져온다. "국토부 요즘 뭐 냈어?" 같은 질문에 쓴다.
Args:
ministry (string[], 필수): 기관코드 배열(예: ["MOLIT"]). 코드는 onegov_list_ministries 로 확인.
doc_type (string[], 선택): 특정 유형만(예: ["press_release"]).
query (string, 선택): 부처 내에서 다시 좁힐 검색어.
days (number, 1~365, 선택): 최근 N일로 제한. 지정하면 from 을 자동 계산한다.
size (number, 1~50, 기본 20) / page (number, 기본 1)
response_format ('markdown'|'json', 기본 markdown)
Returns: onegov_search 와 동일한 형식(항상 최신순 정렬).
Examples:
"국토부 최근 보도자료" → ministry=["MOLIT"], doc_type=["press_release"], days=30
"중기부가 이번 달 낸 공고" → ministry=["MSS"], doc_type=["notice"], days=30
Inputs: ministry (required), days, page, size, +3 more.
onegov_research_topic주제 브리핑(검색+전문 자동 수집)ARead-onlyIdempotent
한 주제에 대해 검색을 돌린 뒤, 상위 문서 몇 건의 본문까지 자동으로 받아와 한 번에 돌려준다. "이 주제 정부 자료 정리해줘" 같은 요청에서 검색→전문조회 왕복을 줄여 준다.
Args:
query (string, 필수): 조사할 주제.
depth (number, 1~5, 기본 3): 본문까지 받아올 상위 문서 수. 많을수록 느리고 응답이 길다.
doc_type (string[], 선택) / ministry (string[], 선택) / from / to: onegov_search 와 동일한 필터.
chars_per_doc (number, 1000~10000, 기본 3000): 문서당 본문 길이 상한.
response_format ('markdown'|'json', 기본 markdown)
Returns: markdown: 검색 요약(총 건수·상위 목록) + 상위 depth 건의 본문 발췌(기관·발행일·원문링크 포함). json: { query, total, candidates[], documents[] }
Examples:
"AI 기본법 관련 정부 자료 정리해줘" → query="인공지능 기본법", depth=3
단순히 목록만 필요하면 onegov_search 를 쓸 것(더 빠르다).
Inputs: query (required), to, from, depth, +4 more.
onegov_search정부 공개자료 통합검색ARead-onlyIdempotent
대한민국 중앙행정기관 약 50곳의 보도자료·정책·법령·통계·정보공개·자주묻는질문·고시공고를 한 번에 검색한다(약 9만 건 색인).
부처 이름을 몰라도 자연어로 검색된다. 하이브리드(키워드+의미) 검색이 기본.
Args:
query (string, 선택): 검색어. 비우면 필터 조건만으로 최신 문서를 훑는다. 짧고 일반적인 명사구가 잘 맞는다(예: "청년 월세", "반도체 특별법").
doc_type (string[], 선택): press_release | policy | law | statistic | info_disclosure | faq | notice
ministry (string[], 선택): 기관코드(예: MSS=중소벤처기업부, MOLIT=국토교통부). 코드는 onegov_list_ministries 로 확인.
category (string[], 선택): 콘텐츠 분류. 지원사업은 "grant".
region (string[], 선택): 지역명(예: "서울특별시", "경기도", "전국").
law_ref (string[], 선택): 관련 법령명 정확일치(예: "중소기업창업 지원법").
from / to (YYYY-MM-DD, 선택): 발행일 범위.
sort ('relevance'|'date_desc'|'date_asc', 기본 relevance): 정확도순 / 최신순 / 오래된순.
mode ('hybrid'|'fulltext'|'semantic', 기본 hybrid): 검색 방식.
page (number, 기본 1) / size (number, 1~50, 기본 20): 페이지네이션.
include_facets (boolean, 기본 true): 결과 분포(문서유형·기관·연도·지역·법령) 요약 포함 여부.
response_format ('markdown'|'json', 기본 markdown)
Returns: markdown: 총 건수 + 결과별 제목/유형/기관/발행일/문서 id/원문 링크/요약, 그리고 패싯 요약. json: { query, page, size, total, results[], facets{}, meta{} } — results[i]에 id, doc_type, title, summary, ministry_code, ministry_name, published_at, source_url, kogl_type, law_ref[], region, attachments[], score 포함.
Examples:
"작년에 나온 청년 주거 지원 정책" → query="청년 주거 지원", from="2025-01-01", to="2025-12-31"
"중기부가 낸 창업 공고만" → query="창업", ministry=["MSS"], doc_type=["notice"]
"개인정보보호 관련 법령 최신순" → query="개인정보", doc_type=["law"], sort="date_desc"
쓰지 말 것: 문서 전문이 필요할 때(→ onegov_get_document), 마감임박 지원사업 목록(→ onegov_deadline_grants)
Errors:
잘못된 doc_type/sort 값은 어떤 필드가 틀렸는지 알려준다.
429는 레이트리밋이므로 잠시 후 재시도.
Inputs: to, from, mode, page, +10 more.
onegov_suggest_keywords검색어 자동완성ARead-onlyIdempotent
입력한 앞글자로 시작하는, 실제 색인에 존재하는 검색어를 돌려준다. 검색 결과가 0건일 때 정확한 용어를 찾는 용도로 먼저 쓰면 좋다.
Args:
prefix (string, 필수): 앞글자(예: "청년", "반도체").
response_format ('markdown'|'json', 기본 markdown)
Returns: { suggestions: [{ text, doc_type }] }
Examples:
"청년" → 청년도약계좌, 청년월세지원, 청년기본법 …
쓰지 말 것: 실제 문서를 찾을 때(→ onegov_search)
Inputs: prefix (required), response_format.
onegov_trending_keywords많이 등장하는 주제어ARead-onlyIdempotent
공개자료 제목에서 자주 등장하는 상위 키워드와 등장 횟수를 돌려준다. "요즘 정부가 뭘 많이 하나"를 훑거나 검색어 후보를 잡을 때 쓴다.
Args:
limit (number, 1~100, 기본 30)
response_format ('markdown'|'json', 기본 markdown)
Returns: { keywords: [{ text, count, weight }] }
Inputs: limit, response_format.
searchSearch (ChatGPT 호환)ARead-onlyIdempotent
ChatGPT 커넥터/딥리서치 규격에 맞춘 검색 도구. 대한민국 정부 공개자료를 검색해 {id, title, url} 목록을 돌려준다. 일반적인 MCP 클라이언트에서는 필터가 풍부한 onegov_search 를 쓰는 편이 낫다.
Args: query (string, 필수) Returns: { results: [{ id, title, url }] } 를 JSON 문자열로.
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly distinct purpose: general search, document retrieval, keyword suggestions, ministry listing, trending keywords, deadline grants, support program search, ministry latest, research topic, and two connector-specific tools. No overlap that would cause confusion.
Most tools follow a consistent 'onegov_verb_noun' pattern. However, the last two tools ('search' and 'fetch') break this pattern by omitting the prefix, leading to a minor inconsistency.
With 11 tools, the set is well-scoped for the domain of Korean government document search. Each tool provides distinct functionality without being excessive or insufficient.
The tool surface covers the full workflow: searching with filters, retrieving documents, exploring ministries, trending keywords, deadline grants, support programs, and in-depth research. No obvious gaps for the stated purpose.
Related MCP Connectors
Korean policy & finance facts with primary-source citations (laws, gov notices) for AI agents
Korean policy & finance facts with primary-source citations (laws, gov notices) for AI agents
Korean law: statutes, precedents, ordinances, treaties and citation verification (법제처 API).
Find official Korean public datasets, agency-site menus, disclosure listings, and source URLs.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI programs to search and retrieve approved public regulations with citations, supporting PDF, HWP, HWPX, and DOCX formats.43MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI to query real-time Korean public data including weather, real estate prices, air quality, economic indicators, and business registration via natural language.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to search and retrieve Korean laws, regulations, administrative rules, legal interpretations, and precedents via official APIs for legal review workflows.1MIT
- FlicenseNot gradedqualityDmaintenanceEnables read-only search and retrieval of press releases from 12 South Korean government agencies, returning metadata like title, agency, publication date, and original URL.3-