Skip to main content
Glama
korea-onegov-mcp

korea-onegov-mcp

by socialkim

korea-onegov-mcp

Deploy with Vercel

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개)

도구

하는 일

onegov_search

통합검색. 문서유형·기관·지역·법령·발행일 범위·정렬·검색모드 전체 필터 지원

onegov_get_document

문서 id로 전문 + 첨부 + 관련법령 + 연관문서 조회

onegov_suggest_keywords

실제 색인된 검색어 자동완성 (0건 나올 때 먼저 쓰기)

onegov_list_ministries

기관코드 목록과 보유 문서 수 (ministry 필터용 코드 확인)

onegov_trending_keywords

공개자료 제목에 자주 등장하는 상위 주제어

onegov_deadline_grants

마감임박 지원사업 공고 (D-day·기관 필터)

onegov_find_support_programs

지원사업·공고 주제 검색 (범위를 미리 좁힌 편의 도구)

onegov_ministry_latest

특정 부처의 최근 N일 자료를 최신순으로

onegov_research_topic

검색 → 상위 문서 본문 자동 수집까지 한 번에 (주제 브리핑)

search / fetch

ChatGPT 커넥터·딥리서치 규격 호환용 (ONEGOV_CHATGPT_COMPAT=off 로 끌 수 있음)

모든 도구는 읽기 전용이며, 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.cmd

git·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 --prod

A-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 웹/데스크톱에 등록

  1. Claude 설정 → Connectors

  2. + Add custom connector

  3. 이름: OneGov 정부자료, URL: https://<프로젝트명>.vercel.app/mcp

  4. Add → 대화창의 도구 아이콘에서 켜고 사용

인증 설정은 비워 두면 됩니다(무인증 서버).

A-4. ChatGPT에 등록

ChatGPT의 커스텀 MCP 커넥터는 개발자 모드가 필요하며 Pro/Team/Enterprise/Edu 플랜에서 제공됩니다.

  1. 설정 → Connectors → Advanced → Developer mode 켜기

  2. Connectors → Create

  3. 이름과 서버 URL(https://<프로젝트명>.vercel.app/mcp) 입력, 인증은 No authentication

  4. 신뢰 확인에 체크하고 생성

이 서버는 딥리서치 규격에 맞춘 search / fetch 도구를 함께 제공하므로 딥리서치 커넥터로도 붙습니다.


B. 로컬(stdio)로 쓰기 — Claude 데스크톱앱 / Claude Code / Cursor

cd korea-onegov-mcp
npm install
node src/index.js --help

Claude 데스크톱앱

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로 도구 직접 호출해 보기

환경변수

이름

기본값

설명

PORT

3000

로컬 HTTP 모드 포트

HOST

127.0.0.1

로컬 HTTP 모드 바인딩 주소

ONEGOV_API_BASE

https://korea-onegov.vercel.app

OneGov API 베이스 URL

ONEGOV_TIMEOUT_MS

25000

외부 API 타임아웃

ONEGOV_CHATGPT_COMPAT

(켜짐)

off 로 두면 search/fetch 도구를 등록하지 않음


테스트

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 tools
fetchFetch (ChatGPT 호환)A
Read-onlyIdempotent

ChatGPT 커넥터/딥리서치 규격에 맞춘 문서 조회 도구. search 가 돌려준 id로 전문을 가져온다.

Args: id (string, 필수) Returns: { id, title, text, url, metadata } 를 JSON 문자열로.

Inputs: id (required).

onegov_deadline_grants마감임박 지원사업 공고A
Read-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지원사업·공고 찾기A
Read-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문서 전문 조회A
Read-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기관(부처) 코드 목록A
Read-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특정 부처 최신 자료A
Read-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주제 브리핑(검색+전문 자동 수집)A
Read-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_suggest_keywords검색어 자동완성A
Read-onlyIdempotent

입력한 앞글자로 시작하는, 실제 색인에 존재하는 검색어를 돌려준다. 검색 결과가 0건일 때 정확한 용어를 찾는 용도로 먼저 쓰면 좋다.

Args:

  • prefix (string, 필수): 앞글자(예: "청년", "반도체").

  • response_format ('markdown'|'json', 기본 markdown)

Returns: { suggestions: [{ text, doc_type }] }

Examples:

  • "청년" → 청년도약계좌, 청년월세지원, 청년기본법 …

  • 쓰지 말 것: 실제 문서를 찾을 때(→ onegov_search)

Inputs: prefix (required), response_format.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI programs to search and retrieve approved public regulations with citations, supporting PDF, HWP, HWPX, and DOCX formats.
      43
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI to query real-time Korean public data including weather, real estate prices, air quality, economic indicators, and business registration via natural language.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to search and retrieve Korean laws, regulations, administrative rules, legal interpretations, and precedents via official APIs for legal review workflows.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -