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

도구	하는 일
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 을 고를 수 있습니다.

---

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 (이 래퍼 코드에 한함). 검색되는 자료의 저작권·이용조건은 각 소관 기관 및 공공누리 조건을 따릅니다.