public-data-api-finder MCP

한국 공공데이터포털(data.go.kr)의 공개 API를 자연어로 검색하고 추천해주는 Model Context Protocol(MCP) 서버

Claude, Cursor 등 MCP를 지원하는 AI 어시스턴트에 연결하면, 아이디어를 설명하는 것만으로 관련 공공 API를 자동으로 찾아 추천해줍니다.

MCP란?

Model Context Protocol(MCP) 은 Anthropic이 만든 오픈 표준으로, AI 어시스턴트가 외부 도구·데이터 소스를 표준화된 방식으로 호출할 수 있게 하는 프로토콜입니다.

이 프로젝트는 MCP 서버로 동작하며, AI가 대화 중 필요하다고 판단하면 자동으로 공공데이터 검색 도구를 호출합니다. 사용자는 별도 코드를 짜거나 API를 직접 호출할 필요 없이, 자연어로 대화하기만 하면 됩니다.

사용자: "실시간 버스 위치 데이터가 필요한 앱을 만들고 싶어"
AI: (내부적으로 recommend_public_apis_for_idea 호출)
AI: "국토교통부_버스위치정보조회서비스 API를 추천합니다. 실시간 REST API로..."

아키텍처

┌─────────────────────────────────────────────────────────┐
│                   AI 어시스턴트 (Claude / Cursor)          │
│                  (자연어 입력 처리 + 응답 생성)              │
└───────────────────────┬─────────────────────────────────┘
                        │ MCP (stdio)
                        ▼
┌─────────────────────────────────────────────────────────┐
│              public-data-api-finder MCP 서버              │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │  recommend_  │  │   search_    │  │  get_dataset_ │ │
│  │  public_apis │  │   public_    │  │    detail     │ │
│  │  _for_idea   │  │   datasets   │  │               │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬────────┘ │
│         │                 │                  │          │
│  ┌──────▼─────────────────▼──────────────────▼───────┐  │
│  │  키워드 추출 → 검색 → 정규화 → 점수화 → 캐시       │  │
│  └───────────────────────┬───────────────────────────┘  │
│                          │ 지수 백오프 재시도              │
└──────────────────────────┼──────────────────────────────┘
                           │ HTTPS POST (JSON)
                           ▼
┌─────────────────────────────────────────────────────────┐
│   공공데이터활용지원센터_공공데이터포털 검색 서비스 (ID: 15112888)  │
│       api.odcloud.kr/api/GetSearchDataList/v1/searchData  │
└─────────────────────────────────────────────────────────┘

제공 도구 (MCP Tools)

1. recommend_public_apis_for_idea

아이디어 텍스트를 입력하면 관련 공공 API를 자동으로 검색·점수화·추천합니다.

내부 처리 흐름

1. 키워드 추출 — 한국어 형태소 분석으로 핵심 키워드 추출, 도메인 동의어 확장 (예: "날씨" → 기상, 기온, 강수)
2. 병렬 검색 — 추출된 키워드별로 공공데이터 API를 동시 호출
3. 정규화 — 다양한 응답 구조를 내부 통일 포맷으로 변환 + 중복 제거
4. 점수화 — 아래 알고리즘으로 100점 만점 산출
5. 캐시 저장 — 동일 질의 재요청 시 API 재호출 없이 반환

점수화 알고리즘

파라미터

예시 응답

{
  "ideaSummary": "지역 축제 알림 앱",
  "extractedKeywords": ["지역", "축제", "알림", "행사", "문화행사"],
  "recommendations": [
    {
      "title": "대전광역시 문화축제 정보",
      "provider": "대전광역시",
      "type": "API",
      "updateCycle": "2024-11-12",
      "score": 72,
      "reason": "'축제', '행사', '문화행사'와(과) 관련됩니다. OpenAPI 형태로 직접 호출 가능합니다. 대전광역시 제공.",
      "detailUrl": "https://www.data.go.kr/data/15006969/openapi.do"
    }
  ]
}

2. get_dataset_detail

추천된 데이터셋의 실제 API 명세를 상세 조회합니다. data.go.kr 상세 페이지에서 Swagger spec을 자동 파싱해 호출에 필요한 정보를 모두 반환합니다.

파라미터

예시 응답

{
  "title": "공공데이터 포털 검색 서비스",
  "baseUrl": "https://api.odcloud.kr/api",
  "endpoints": [
    {
      "method": "POST",
      "path": "/GetSearchDataList/v1/searchData",
      "summary": "데이터셋 검색",
      "parameters": [
        { "name": "keyword", "in": "body", "required": false, "type": "string", "description": "검색어" },
        { "name": "page",    "in": "body", "required": false, "type": "integer", "description": "페이지 번호" },
        { "name": "size",    "in": "body", "required": false, "type": "integer", "description": "결과 수" }
      ]
    }
  ],
  "authMethod": "쿼리 파라미터: serviceKey",
  "swaggerUrl": "https://infuser.odcloud.kr/api/stages/43698/api-docs",
  "detailPageUrl": "https://www.data.go.kr/data/15112888/openapi.do"
}

3. search_public_datasets

키워드로 공공데이터를 직접 검색합니다. 추천 없이 원시 결과가 필요할 때 사용합니다.

파라미터

4. refine_recommendations

이전 추천 결과를 API 재호출 없이 재필터링·재정렬합니다. 토큰과 API 호출 횟수를 절약합니다.

파라미터

캐시 전략

사전 요구사항

• Node.js 18 이상
• pnpm 8 이상
• 공공데이터포털 검색 서비스 API 키
  1. data.go.kr 회원가입 후 로그인
  2. 공공데이터활용지원센터_공공데이터포털 검색 서비스 (ID: 15112888) 활용 신청
  3. 마이페이지 → 데이터 활용 → Open API → 개발계정 상세보기에서 일반 인증키(Encoding) 복사

설치

git clone https://github.com/boam79/public-data-api-finder.git
cd public-data-api-finder
pnpm install
pnpm build

환경변수 설정

cp .env.example .env

.env 파일을 열어 발급받은 인증키(Encoding)를 입력합니다.

PUBLIC_DATA_SERVICE_KEY=hIa%2BwCHFe509o...  # 발급받은 Encoding 키

.env 파일은 .gitignore에 포함되어 있어 원격 저장소에 업로드되지 않습니다.

Cursor에 MCP 등록

~/.cursor/mcp.json 파일에 추가합니다.

{
  "mcpServers": {
    "public-data-api-finder": {
      "command": "node",
      "args": ["/절대경로/public-data-api-finder/dist/server.js"],
      "env": {
        "PUBLIC_DATA_SERVICE_KEY": "발급받은_인증키(Encoding)"
      }
    }
  }
}

Cursor를 재시작하면 AI 채팅에서 도구가 활성화됩니다.

Claude Desktop에 MCP 등록

~/Library/Application Support/Claude/claude_desktop_config.json 파일에 추가합니다.

{
  "mcpServers": {
    "public-data-api-finder": {
      "command": "node",
      "args": ["/절대경로/public-data-api-finder/dist/server.js"],
      "env": {
        "PUBLIC_DATA_SERVICE_KEY": "발급받은_인증키(Encoding)"
      }
    }
  }
}

Claude Desktop을 재시작하면 도구가 활성화됩니다.

개발

pnpm test    # vitest 단위 테스트 (20개)
pnpm build   # TypeScript 컴파일
pnpm dev     # 변경 감지 자동 재빌드

기술 스택

버전 히스토리

v1.0.0 → v1.4.0 주요 변화

라이선스

MIT