Skip to main content
Glama
공공데이터포털 MCP Server

공공데이터포털 MCP Server

by saladent074
README.md
# 공공데이터포털 MCP Server (data.go.kr Multi-API)

공공데이터포털(data.go.kr)의 오픈API 4종을 Claude 같은 MCP 클라이언트에서 쓸 수 있게 해 주는 MCP 서버입니다.
**인증키 하나**로 공휴일, 날씨, 미세먼지, 아파트 실거래가를 자연어로 조회할 수 있습니다.

> API 키는 코드에 들어 있지 않습니다. 사용하는 사람이 **본인의 공공데이터포털 인증키를 직접 입력**해야 합니다.

## 제공 도구 (Tools)

| 도구 | 데이터 출처 | 설명 | 주요 입력값 |
|---|---|---|---|
| `get_special_days` | 한국천문연구원 특일 정보 | 공휴일(대체·임시 포함), 국경일, 기념일, 24절기, 잡절 | `year`, `month`, `kind` |
| `get_weather_forecast` | 기상청 단기예보 | 최근 발표 기준 시간대별 기온·하늘·강수확률·습도 | `city` 또는 `lat`/`lon` 또는 `nx`/`ny`, `hours` |
| `get_current_weather` | 기상청 초단기실황 | 현재 기온·습도·강수·풍속 | `city` 또는 `lat`/`lon` |
| `get_air_quality` | 에어코리아 대기오염정보 | 시도별 실시간 PM10·PM2.5·오존·통합대기지수 | `sido`, `station` |
| `get_apartment_trades` | 국토교통부 아파트 매매 실거래가(상세) | 지역·계약월별 거래 내역과 요약 통계 | `year_month`, `region_code` 또는 `seoul_gu`, `apartment` |
| `check_api_status` | - | 4개 API 시험 호출로 인증키·활용신청 상태 점검 | 없음 |

- `city` 지원 도시: 서울, 부산, 대구, 인천, 광주, 대전, 울산, 세종, 수원, 춘천, 청주, 전주, 창원, 포항, 제주, 강릉 (그 외 지역은 위도/경도 입력)
- `seoul_gu`: 서울 25개 자치구 이름. 그 외 지역은 법정동코드 앞 5자리(`region_code`)를 [행정표준코드관리시스템](https://www.code.go.kr)에서 확인

## 1. 공공데이터포털 인증키 준비

1. [data.go.kr](https://www.data.go.kr) 회원가입 후 로그인
2. 아래 4개 API 페이지에서 각각 **[활용신청]**

| API | 신청 페이지 |
|---|---|
| 한국천문연구원 특일 정보 | https://www.data.go.kr/data/15012690/openapi.do |
| 기상청 단기예보 조회서비스 | https://www.data.go.kr/data/15084084/openapi.do |
| 한국환경공단 에어코리아 대기오염정보 | https://www.data.go.kr/data/15073861/openapi.do |
| 국토교통부 아파트 매매 실거래가 상세 자료 | https://www.data.go.kr/data/15126468/openapi.do |

3. 마이페이지 → 데이터활용 → Open API → 활용신청 현황에서 **일반 인증키(Decoding)** 복사
   - 4개 API 모두 같은 인증키를 사용합니다.
   - 신청 직후에는 키 등록에 시간이 걸려 `SERVICE_KEY_IS_NOT_REGISTERED_ERROR`가 날 수 있습니다.

## 2. 설치

```bash
git clone https://github.com/saladent074/publicdata-mcp.git
cd publicdata-mcp

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

python -m pip install -r requirements.txt
```

## 3. API 키 설정 (둘 중 하나)

### 방법 A. MCP 클라이언트 설정에 입력 (권장)

아래 "Claude Desktop 연결"의 `env` 항목에 인증키를 넣습니다.

### 방법 B. `.env` 파일 사용

```bash
# Windows
copy .env.example .env
# macOS / Linux
cp .env.example .env
```

`.env`를 열어 인증키를 입력합니다.

```
DATA_GO_KR_SERVICE_KEY=발급받은_인증키
```

> 두 방법을 모두 쓰면 클라이언트 설정(`env`) 값이 우선합니다. Decoding 키를 권장하지만, Encoding 키(`%2B` 등 포함)를 넣어도 자동으로 처리됩니다.

## 4. Claude Desktop 연결

Claude Desktop → **설정 → 개발자 → 구성 편집**을 눌러 `claude_desktop_config.json`을 엽니다.
(설치 방식에 따라 파일 위치가 다르므로 이 버튼으로 여는 것이 가장 확실합니다.)

`mcpServers` 안에 아래 블록을 추가합니다. 기존 서버가 있으면 지우지 말고 쉼표(`,`)로 구분해 추가하세요.

```json
{
  "mcpServers": {
    "publicdata": {
      "command": "C:\\path\\to\\publicdata-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\publicdata-mcp\\server.py"],
      "env": {
        "DATA_GO_KR_SERVICE_KEY": "발급받은_인증키"
      }
    }
  }
}
```

- `command`: 가상환경의 Python 경로 (macOS/Linux는 `.venv/bin/python`)
- Windows 경로의 `\`는 `\\`로 두 번 씁니다.
- 저장 후 Claude Desktop을 **트레이에서 완전히 종료**한 뒤 다시 실행합니다.
- 설정 → 개발자 화면에서 `publicdata`가 **실행 중**이면 연결 완료입니다.

## 5. 사용 예시

- "API 상태 점검해줘" → `check_api_status`
- "올해 남은 공휴일 알려줘"
- "내일 서울 날씨 시간대별로 알려줘"
- "지금 부산 기온 몇 도야?"
- "서울 강남 미세먼지 어때?"
- "2026년 10월 강남구 아파트 실거래가 상위 10건 보여줘"

## 문제 해결

| 증상 | 확인할 것 |
|---|---|
| `DATA_GO_KR_SERVICE_KEY가 설정되지 않았습니다` | `env` 또는 `.env`에 키가 들어갔는지 |
| `SERVICE_KEY_IS_NOT_REGISTERED_ERROR` | 해당 API 활용신청·승인 여부, 신청 직후라면 잠시 후 재시도 |
| `SERVICE_ACCESS_DENIED_ERROR` | 그 API를 활용신청하지 않음 → 해당 API 페이지에서 활용신청 |
| `LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR` | 일일 호출 한도 초과 → 다음 날 재시도 |
| 실거래가 최근 월 건수가 적음 | 계약 후 30일 신고기한 때문. 지난달 이전 자료로 확인 |
| Claude에 도구가 보이지 않음 | 설정 JSON 문법(쉼표), 경로, Claude Desktop 완전 재시작 |
| Windows에서 `pip.exe`가 차단됨 | `pip` 대신 `python -m pip` 사용 |

## 보안 주의

- `.env` 파일과 인증키는 **절대 GitHub에 올리지 마세요.** (`.gitignore`에 등록됨)
- 서버는 인증키가 로그에 남지 않도록 HTTP 요청 로그를 끕니다.
- 키가 노출되었다면 data.go.kr 마이페이지에서 재발급하세요.

## 데이터 출처 및 이용조건

- 한국천문연구원 특일 정보, 기상청 단기예보 조회서비스, 한국환경공단 에어코리아 대기오염정보, 국토교통부 아파트 매매 실거래가 상세 자료 — 공공데이터포털(data.go.kr)
- 각 데이터의 이용허락범위(공공누리 유형 등)는 해당 API 페이지에서 확인하고 출처를 표시해 주세요.

## 기술 정보

- MCP Python SDK 2.x (`mcp.server.mcpserver.MCPServer`), stdio 전송
- XML/JSON 응답 자동 판별, 공공데이터포털 게이트웨이 오류 메시지 해석
- 위경도 → 기상청 격자 변환(LCC) 내장

## License

MIT