# 국토교통부 아파트 매매 실거래가 MCP Server
국토교통부의 아파트 매매 실거래가 데이터를 조회할 수 있는 MCP (Model Context Protocol) 서버입니다.
## 🎯 주요 기능
- **아파트 매매 실거래가 검색**: 지역코드와 거래년월로 실거래 정보 조회
- **지역코드 조회**: 한국의 시/군/구 지역코드 검색 및 조회
- **스마트 페이지네이션**: 대용량 데이터 효율적 처리
- **stats 모드**: 통계 및 샘플 데이터만 조회
- **page 모드**: 페이지별 조회 (100건씩)
- **auto 모드**: 자동 전체 조회 (500건 이하)
- **상세 정보 제공**: 거래금액, 전용면적, 층수, 건축년도 등 핵심 정보
## 📦 설치
### PyPI를 통한 설치 (권장)
```bash
pip install data-go-mcp.apartment-trade
```
또는 `uvx`를 사용한 실행:
```bash
uvx data-go-mcp.apartment-trade@latest
```
### 소스에서 설치
```bash
git clone https://github.com/Koomook/data-go-mcp-servers.git
cd data-go-mcp-servers/src/apartment-trade
uv sync
```
## 🔑 API 키 발급
1. [data.go.kr](https://www.data.go.kr) 회원가입
2. [국토교통부 아파트매매 실거래가](https://www.data.go.kr/data/15126500/openapi.do) API 신청
3. 발급받은 API 키를 환경변수로 설정:
```bash
export API_KEY="your-api-key-here"
```
## 🚀 사용법
### Claude Desktop 설정
`claude_desktop_config.json`에 다음 설정 추가:
```json
{
"mcpServers": {
"apartment-trade": {
"command": "uvx",
"args": ["data-go-mcp.apartment-trade@latest"],
"env": {
"API_KEY": "your-api-key-here"
}
}
}
}
```
### 로컬 개발 환경 설정
```json
{
"mcpServers": {
"apartment-trade": {
"command": "/path/to/venv/bin/python",
"args": [
"-m",
"data_go_mcp.apartment_trade.server"
],
"cwd": "/path/to/data-go-mcp-servers/src/apartment-trade",
"env": {
"API_KEY": "your-api-key-here"
}
}
}
}
```
## 🛠️ 제공 도구
### 1. search_apartment_trades
아파트 매매 실거래가를 검색합니다.
**파라미터:**
- `region` (필수): 지역명 또는 지역코드 (예: "강남구", "11680")
- `year_month` (필수): 거래년월 YYYYMM 형식 (예: "202401")
- `mode` (선택): 조회 모드 (기본값: "auto")
- `"stats"`: 통계 정보와 샘플 데이터만 조회
- `"page"`: 특정 페이지 조회 (page 파라미터 필요)
- `"auto"`: 자동으로 전체 데이터 조회 (500건 이하만)
- `page` (선택): 페이지 번호 (mode="page"일 때 사용, 기본값: 1)
- `size` (선택): 페이지당 결과 수 (mode="page"일 때 사용, 기본값: 100, 최대: 100)
**사용 예시:**
```
"2024년 1월 강남구의 아파트 매매 실거래가를 조회해줘"
"서울 송파구 202312 아파트 거래 내역 보여줘"
"지역코드 11680으로 2024년 상반기 거래 검색"
```
### 2. get_region_codes
한국의 시/군/구 지역코드를 조회합니다.
**파라미터:**
- `search` (선택): 검색할 지역명
**사용 예시:**
```
"서울의 모든 구 지역코드 알려줘"
"경기도 지역코드 목록 보여줘"
"강남 관련 지역코드 검색"
```
## 📊 응답 데이터 형식
### 거래 정보 필드
**핵심 정보 (v1.0.0 최적화):**
- `apt_nm`: 아파트 이름
- `deal_year/month/day`: 거래 날짜
- `deal_amount`: 거래금액 (만원)
- `exclu_use_ar`: 전용면적 (㎡)
- `floor`: 층
- `build_year`: 건축년도
**추가 정보 (API 응답에 포함):**
- `sgg_cd`: 시군구 코드
- `umd_nm`: 법정동 이름
- `apt_dong`: 아파트 동 정보
- `jibun`: 지번
## 🏙️ 지원 지역
### 특별시/광역시
- 서울특별시 (11000) 및 25개 구
- 부산광역시 (26000) 및 16개 구/군
- 대구광역시 (27000) 및 8개 구/군
- 인천광역시 (28000) 및 10개 구/군
- 광주광역시 (29000) 및 5개 구
- 대전광역시 (30000) 및 5개 구
- 울산광역시 (31000) 및 5개 구/군
- 세종특별자치시 (36110)
### 경기도 주요 도시
- 수원시, 성남시, 안양시, 부천시, 고양시, 용인시 등 31개 시
## 🧪 테스트
```bash
# 단위 테스트 실행
cd src/apartment-trade
uv run pytest tests/
# 커버리지 포함
uv run pytest tests/ --cov=data_go_mcp.apartment_trade
```
## 📝 라이선스
Apache License 2.0
## 🤝 기여
기여를 환영합니다! [CONTRIBUTING.md](../../CONTRIBUTING.md)를 참조하세요.
## 🐛 문제 신고
이슈는 [GitHub Issues](https://github.com/Koomook/data-go-mcp-servers/issues)에 등록해주세요.
## 📚 관련 문서
- [data.go.kr API 문서](https://www.data.go.kr/data/15126500/openapi.do)
- [MCP (Model Context Protocol)](https://modelcontextprotocol.io/)
- [프로젝트 홈페이지](https://github.com/Koomook/data-go-mcp-servers)
Raw data
{
"_id": null,
"home_page": null,
"name": "data-go-mcp.apartment-trade",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "apartment, api, data.go.kr, korea, mcp, real-estate",
"author": "Data.go.kr MCP Servers Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cc/6b/a9c2ead52edf8052db7878013e4b0751732f6d24fdc7260f4466c53edac4/data_go_mcp_apartment_trade-1.0.1.tar.gz",
"platform": null,
"description": "# \uad6d\ud1a0\uad50\ud1b5\ubd80 \uc544\ud30c\ud2b8 \ub9e4\ub9e4 \uc2e4\uac70\ub798\uac00 MCP Server\n\n\uad6d\ud1a0\uad50\ud1b5\ubd80\uc758 \uc544\ud30c\ud2b8 \ub9e4\ub9e4 \uc2e4\uac70\ub798\uac00 \ub370\uc774\ud130\ub97c \uc870\ud68c\ud560 \uc218 \uc788\ub294 MCP (Model Context Protocol) \uc11c\ubc84\uc785\ub2c8\ub2e4.\n\n## \ud83c\udfaf \uc8fc\uc694 \uae30\ub2a5\n\n- **\uc544\ud30c\ud2b8 \ub9e4\ub9e4 \uc2e4\uac70\ub798\uac00 \uac80\uc0c9**: \uc9c0\uc5ed\ucf54\ub4dc\uc640 \uac70\ub798\ub144\uc6d4\ub85c \uc2e4\uac70\ub798 \uc815\ubcf4 \uc870\ud68c\n- **\uc9c0\uc5ed\ucf54\ub4dc \uc870\ud68c**: \ud55c\uad6d\uc758 \uc2dc/\uad70/\uad6c \uc9c0\uc5ed\ucf54\ub4dc \uac80\uc0c9 \ubc0f \uc870\ud68c\n- **\uc2a4\ub9c8\ud2b8 \ud398\uc774\uc9c0\ub124\uc774\uc158**: \ub300\uc6a9\ub7c9 \ub370\uc774\ud130 \ud6a8\uc728\uc801 \ucc98\ub9ac\n - **stats \ubaa8\ub4dc**: \ud1b5\uacc4 \ubc0f \uc0d8\ud50c \ub370\uc774\ud130\ub9cc \uc870\ud68c\n - **page \ubaa8\ub4dc**: \ud398\uc774\uc9c0\ubcc4 \uc870\ud68c (100\uac74\uc529)\n - **auto \ubaa8\ub4dc**: \uc790\ub3d9 \uc804\uccb4 \uc870\ud68c (500\uac74 \uc774\ud558)\n- **\uc0c1\uc138 \uc815\ubcf4 \uc81c\uacf5**: \uac70\ub798\uae08\uc561, \uc804\uc6a9\uba74\uc801, \uce35\uc218, \uac74\ucd95\ub144\ub3c4 \ub4f1 \ud575\uc2ec \uc815\ubcf4\n\n## \ud83d\udce6 \uc124\uce58\n\n### PyPI\ub97c \ud1b5\ud55c \uc124\uce58 (\uad8c\uc7a5)\n\n```bash\npip install data-go-mcp.apartment-trade\n```\n\n\ub610\ub294 `uvx`\ub97c \uc0ac\uc6a9\ud55c \uc2e4\ud589:\n\n```bash\nuvx data-go-mcp.apartment-trade@latest\n```\n\n### \uc18c\uc2a4\uc5d0\uc11c \uc124\uce58\n\n```bash\ngit clone https://github.com/Koomook/data-go-mcp-servers.git\ncd data-go-mcp-servers/src/apartment-trade\nuv sync\n```\n\n## \ud83d\udd11 API \ud0a4 \ubc1c\uae09\n\n1. [data.go.kr](https://www.data.go.kr) \ud68c\uc6d0\uac00\uc785\n2. [\uad6d\ud1a0\uad50\ud1b5\ubd80 \uc544\ud30c\ud2b8\ub9e4\ub9e4 \uc2e4\uac70\ub798\uac00](https://www.data.go.kr/data/15126500/openapi.do) API \uc2e0\uccad\n3. \ubc1c\uae09\ubc1b\uc740 API \ud0a4\ub97c \ud658\uacbd\ubcc0\uc218\ub85c \uc124\uc815:\n\n```bash\nexport API_KEY=\"your-api-key-here\"\n```\n\n## \ud83d\ude80 \uc0ac\uc6a9\ubc95\n\n### Claude Desktop \uc124\uc815\n\n`claude_desktop_config.json`\uc5d0 \ub2e4\uc74c \uc124\uc815 \ucd94\uac00:\n\n```json\n{\n \"mcpServers\": {\n \"apartment-trade\": {\n \"command\": \"uvx\",\n \"args\": [\"data-go-mcp.apartment-trade@latest\"],\n \"env\": {\n \"API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n### \ub85c\uceec \uac1c\ubc1c \ud658\uacbd \uc124\uc815\n\n```json\n{\n \"mcpServers\": {\n \"apartment-trade\": {\n \"command\": \"/path/to/venv/bin/python\",\n \"args\": [\n \"-m\",\n \"data_go_mcp.apartment_trade.server\"\n ],\n \"cwd\": \"/path/to/data-go-mcp-servers/src/apartment-trade\",\n \"env\": {\n \"API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n## \ud83d\udee0\ufe0f \uc81c\uacf5 \ub3c4\uad6c\n\n### 1. search_apartment_trades\n\n\uc544\ud30c\ud2b8 \ub9e4\ub9e4 \uc2e4\uac70\ub798\uac00\ub97c \uac80\uc0c9\ud569\ub2c8\ub2e4.\n\n**\ud30c\ub77c\ubbf8\ud130:**\n- `region` (\ud544\uc218): \uc9c0\uc5ed\uba85 \ub610\ub294 \uc9c0\uc5ed\ucf54\ub4dc (\uc608: \"\uac15\ub0a8\uad6c\", \"11680\")\n- `year_month` (\ud544\uc218): \uac70\ub798\ub144\uc6d4 YYYYMM \ud615\uc2dd (\uc608: \"202401\")\n- `mode` (\uc120\ud0dd): \uc870\ud68c \ubaa8\ub4dc (\uae30\ubcf8\uac12: \"auto\")\n - `\"stats\"`: \ud1b5\uacc4 \uc815\ubcf4\uc640 \uc0d8\ud50c \ub370\uc774\ud130\ub9cc \uc870\ud68c\n - `\"page\"`: \ud2b9\uc815 \ud398\uc774\uc9c0 \uc870\ud68c (page \ud30c\ub77c\ubbf8\ud130 \ud544\uc694)\n - `\"auto\"`: \uc790\ub3d9\uc73c\ub85c \uc804\uccb4 \ub370\uc774\ud130 \uc870\ud68c (500\uac74 \uc774\ud558\ub9cc)\n- `page` (\uc120\ud0dd): \ud398\uc774\uc9c0 \ubc88\ud638 (mode=\"page\"\uc77c \ub54c \uc0ac\uc6a9, \uae30\ubcf8\uac12: 1)\n- `size` (\uc120\ud0dd): \ud398\uc774\uc9c0\ub2f9 \uacb0\uacfc \uc218 (mode=\"page\"\uc77c \ub54c \uc0ac\uc6a9, \uae30\ubcf8\uac12: 100, \ucd5c\ub300: 100)\n\n**\uc0ac\uc6a9 \uc608\uc2dc:**\n```\n\"2024\ub144 1\uc6d4 \uac15\ub0a8\uad6c\uc758 \uc544\ud30c\ud2b8 \ub9e4\ub9e4 \uc2e4\uac70\ub798\uac00\ub97c \uc870\ud68c\ud574\uc918\"\n\"\uc11c\uc6b8 \uc1a1\ud30c\uad6c 202312 \uc544\ud30c\ud2b8 \uac70\ub798 \ub0b4\uc5ed \ubcf4\uc5ec\uc918\"\n\"\uc9c0\uc5ed\ucf54\ub4dc 11680\uc73c\ub85c 2024\ub144 \uc0c1\ubc18\uae30 \uac70\ub798 \uac80\uc0c9\"\n```\n\n### 2. get_region_codes\n\n\ud55c\uad6d\uc758 \uc2dc/\uad70/\uad6c \uc9c0\uc5ed\ucf54\ub4dc\ub97c \uc870\ud68c\ud569\ub2c8\ub2e4.\n\n**\ud30c\ub77c\ubbf8\ud130:**\n- `search` (\uc120\ud0dd): \uac80\uc0c9\ud560 \uc9c0\uc5ed\uba85\n\n**\uc0ac\uc6a9 \uc608\uc2dc:**\n```\n\"\uc11c\uc6b8\uc758 \ubaa8\ub4e0 \uad6c \uc9c0\uc5ed\ucf54\ub4dc \uc54c\ub824\uc918\"\n\"\uacbd\uae30\ub3c4 \uc9c0\uc5ed\ucf54\ub4dc \ubaa9\ub85d \ubcf4\uc5ec\uc918\"\n\"\uac15\ub0a8 \uad00\ub828 \uc9c0\uc5ed\ucf54\ub4dc \uac80\uc0c9\"\n```\n\n## \ud83d\udcca \uc751\ub2f5 \ub370\uc774\ud130 \ud615\uc2dd\n\n### \uac70\ub798 \uc815\ubcf4 \ud544\ub4dc\n\n**\ud575\uc2ec \uc815\ubcf4 (v1.0.0 \ucd5c\uc801\ud654):**\n- `apt_nm`: \uc544\ud30c\ud2b8 \uc774\ub984\n- `deal_year/month/day`: \uac70\ub798 \ub0a0\uc9dc\n- `deal_amount`: \uac70\ub798\uae08\uc561 (\ub9cc\uc6d0)\n- `exclu_use_ar`: \uc804\uc6a9\uba74\uc801 (\u33a1)\n- `floor`: \uce35\n- `build_year`: \uac74\ucd95\ub144\ub3c4\n\n**\ucd94\uac00 \uc815\ubcf4 (API \uc751\ub2f5\uc5d0 \ud3ec\ud568):**\n- `sgg_cd`: \uc2dc\uad70\uad6c \ucf54\ub4dc\n- `umd_nm`: \ubc95\uc815\ub3d9 \uc774\ub984\n- `apt_dong`: \uc544\ud30c\ud2b8 \ub3d9 \uc815\ubcf4\n- `jibun`: \uc9c0\ubc88\n\n## \ud83c\udfd9\ufe0f \uc9c0\uc6d0 \uc9c0\uc5ed\n\n### \ud2b9\ubcc4\uc2dc/\uad11\uc5ed\uc2dc\n- \uc11c\uc6b8\ud2b9\ubcc4\uc2dc (11000) \ubc0f 25\uac1c \uad6c\n- \ubd80\uc0b0\uad11\uc5ed\uc2dc (26000) \ubc0f 16\uac1c \uad6c/\uad70\n- \ub300\uad6c\uad11\uc5ed\uc2dc (27000) \ubc0f 8\uac1c \uad6c/\uad70\n- \uc778\ucc9c\uad11\uc5ed\uc2dc (28000) \ubc0f 10\uac1c \uad6c/\uad70\n- \uad11\uc8fc\uad11\uc5ed\uc2dc (29000) \ubc0f 5\uac1c \uad6c\n- \ub300\uc804\uad11\uc5ed\uc2dc (30000) \ubc0f 5\uac1c \uad6c\n- \uc6b8\uc0b0\uad11\uc5ed\uc2dc (31000) \ubc0f 5\uac1c \uad6c/\uad70\n- \uc138\uc885\ud2b9\ubcc4\uc790\uce58\uc2dc (36110)\n\n### \uacbd\uae30\ub3c4 \uc8fc\uc694 \ub3c4\uc2dc\n- \uc218\uc6d0\uc2dc, \uc131\ub0a8\uc2dc, \uc548\uc591\uc2dc, \ubd80\ucc9c\uc2dc, \uace0\uc591\uc2dc, \uc6a9\uc778\uc2dc \ub4f1 31\uac1c \uc2dc\n\n## \ud83e\uddea \ud14c\uc2a4\ud2b8\n\n```bash\n# \ub2e8\uc704 \ud14c\uc2a4\ud2b8 \uc2e4\ud589\ncd src/apartment-trade\nuv run pytest tests/\n\n# \ucee4\ubc84\ub9ac\uc9c0 \ud3ec\ud568\nuv run pytest tests/ --cov=data_go_mcp.apartment_trade\n```\n\n## \ud83d\udcdd \ub77c\uc774\uc120\uc2a4\n\nApache License 2.0\n\n## \ud83e\udd1d \uae30\uc5ec\n\n\uae30\uc5ec\ub97c \ud658\uc601\ud569\ub2c8\ub2e4! [CONTRIBUTING.md](../../CONTRIBUTING.md)\ub97c \ucc38\uc870\ud558\uc138\uc694.\n\n## \ud83d\udc1b \ubb38\uc81c \uc2e0\uace0\n\n\uc774\uc288\ub294 [GitHub Issues](https://github.com/Koomook/data-go-mcp-servers/issues)\uc5d0 \ub4f1\ub85d\ud574\uc8fc\uc138\uc694.\n\n## \ud83d\udcda \uad00\ub828 \ubb38\uc11c\n\n- [data.go.kr API \ubb38\uc11c](https://www.data.go.kr/data/15126500/openapi.do)\n- [MCP (Model Context Protocol)](https://modelcontextprotocol.io/)\n- [\ud504\ub85c\uc81d\ud2b8 \ud648\ud398\uc774\uc9c0](https://github.com/Koomook/data-go-mcp-servers)",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "MCP server for Korea apartment trade data from data.go.kr",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/Koomook/data-go-mcp-servers",
"Issues": "https://github.com/Koomook/data-go-mcp-servers/issues",
"Repository": "https://github.com/Koomook/data-go-mcp-servers"
},
"split_keywords": [
"apartment",
" api",
" data.go.kr",
" korea",
" mcp",
" real-estate"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "62c8c3f81d1cc4a050f1c45fbc63b21ea12506fe0b7ab645ec086b50de5c3ed8",
"md5": "7163bdf4d62c789ea718adfdd890a529",
"sha256": "bb732f7c6983bb33a1d01ff61355be19dd7ccba51ca3ea51640c152bf27431b1"
},
"downloads": -1,
"filename": "data_go_mcp_apartment_trade-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7163bdf4d62c789ea718adfdd890a529",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14409,
"upload_time": "2025-08-30T10:47:02",
"upload_time_iso_8601": "2025-08-30T10:47:02.725454Z",
"url": "https://files.pythonhosted.org/packages/62/c8/c3f81d1cc4a050f1c45fbc63b21ea12506fe0b7ab645ec086b50de5c3ed8/data_go_mcp_apartment_trade-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cc6ba9c2ead52edf8052db7878013e4b0751732f6d24fdc7260f4466c53edac4",
"md5": "026e5ad751e49c1e0b58201bb0566a2c",
"sha256": "44936f3f15ce843a48d31bbfa23cecd9bb1d890645f294b846fc46afd3e60f65"
},
"downloads": -1,
"filename": "data_go_mcp_apartment_trade-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "026e5ad751e49c1e0b58201bb0566a2c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19461,
"upload_time": "2025-08-30T10:47:03",
"upload_time_iso_8601": "2025-08-30T10:47:03.906477Z",
"url": "https://files.pythonhosted.org/packages/cc/6b/a9c2ead52edf8052db7878013e4b0751732f6d24fdc7260f4466c53edac4/data_go_mcp_apartment_trade-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 10:47:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Koomook",
"github_project": "data-go-mcp-servers",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "data-go-mcp.apartment-trade"
}
JSON
