Which integrations are available for this server?

Uses python-dotenv for managing environment variables and API keys required for the parking information service. Provides access to [Kakao](/mcp/servers/integrations/kakao) Local API for nationwide parking lot search in South Korea, enabling location-based queries for parking facilities with address information.

주차장 정보 조회 MCP 서버

fastMCP를 사용하여 전국 주차장 정보를 조회하는 MCP (Model Context Protocol) 서버입니다.

주요 특징

전국 주차장 검색: 카카오 로컬 API를 통한 전국 주차장 검색
지역별 정보 제공: 서울/경기 지역은 실시간 정보 및 상세 정보 제공
실시간 주차 정보: 서울 지역 실시간 주차 가능 대수 제공
운영 시간 및 요금 정보: 서울/경기 지역 운영 시간 및 요금 정보 제공
사용자 친화적 에러 메시지: 기술적 용어 없이 명확한 안내 메시지

개발 환경 설정 (Windows)

1. Python 가상환경 생성

PowerShell에서 다음 명령어를 실행하세요:

# Python 3.8 이상이 설치되어 있어야 합니다 python --version # 가상환경 생성 python -m venv venv # 가상환경 활성화 .\venv\Scripts\Activate.ps1

참고: PowerShell 실행 정책 오류가 발생하는 경우:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

또는 Command Prompt(cmd)를 사용하는 경우:

venv\Scripts\activate.bat

2. 필요한 라이브러리 설치

가상환경이 활성화된 상태에서:

pip install --upgrade pip pip install -r requirements.txt

3. 환경 변수 설정

.env.example 파일을 참고하여 .env 파일을 생성하세요:

copy .env.example .env

그리고 .env 파일을 열어서 실제 API 키를 입력하세요.

참고: .env.example 파일이 없는 경우 env.example 파일을 참고하세요.

프로젝트 구조

parking-mcp2/ ├── venv/ # 가상환경 (gitignore됨) ├── .env # 환경 변수 (gitignore됨) ├── env.example # 환경 변수 예시 ├── .gitignore ├── requirements.txt # Python 의존성 ├── README.md ├── test_api.py # API 클라이언트 테스트 ├── test_api_call.py # 실제 API 호출 테스트 ├── test_server.py # 서버 구조 테스트 └── src/ # 소스 코드 ├── __init__.py ├── server.py # MCP 서버 메인 파일 └── api_clients/ # API 클라이언트 모듈 ├── __init__.py ├── kakao_local.py # 카카오 로컬 API (주요 검색 API) ├── seoul_data.py # 서울 열린데이터 (서울 실시간 정보) └── gyeonggi_data.py # 경기데이터드림 (경기 실시간 정보)

API 키 발급 방법

1. 카카오 로컬 API 키

카카오 개발자 콘솔 접속
애플리케이션 생성
앱 설정 > 앱 키에서 REST API 키 복사
제품 설정 > 카카오 로그인 활성화 (필수)
제품 설정 > 로컬 활성화 (필수)
.env 파일에 KAKAO_REST_API_KEY에 입력

주의: "OPEN_MAP_AND_LOCAL" 서비스가 활성화되어 있어야 합니다.

2. 서울 열린데이터 API 키

서울 열린데이터 광장 접속
회원가입 및 로그인
마이페이지 > 인증키 관리에서 인증키 발급
.env 파일에 SEOUL_DATA_API_KEY에 입력

사용 API:

GetParkingInfo: 서울시 공영주차장 실시간 정보

3. 경기데이터드림 API 키

경기데이터드림 접속
회원가입 및 로그인
마이페이지 > 인증키 관리에서 인증키 발급
.env 파일에 GYEONGGI_DATA_API_KEY에 입력

사용 API:

ParkingPlace: 경기도 공영주차장 정보

사용 방법

서버 실행

# 가상환경 활성화 .\venv\Scripts\Activate.ps1 # 서버 실행 (모듈로 실행) $env:PYTHONPATH="src"; python -m src.server

MCP 서버 연결

MCP 클라이언트에서 다음과 같이 연결하세요:

{ "mcpServers": { "parking-mcp": { "command": "python", "args": ["-m", "src.server"], "env": { "PYTHONPATH": "src" } } } }

테스트

# API 클라이언트 초기화 테스트 python test_api.py # 실제 API 호출 테스트 (카카오 API) python test_api_call.py # 서버 구조 테스트 python test_server.py

주요 기능

제공하는 Tool 함수

search_nearby_parking
- 주변 주차장 검색 (카카오 로컬 API 사용)
- 좌표 기반 검색 (위도, 경도, 반경)
- 지역별 정보 자동 추가 (서울/경기/기타)
파라미터:
- latitude: 위도 (필수)
- longitude: 경도 (필수)
- radius: 검색 반경 미터 (기본값: 1000)
get_parking_info
- 특정 주차장 상세 정보 조회
- 주차장 이름 또는 주소로 검색
- 지역별 실시간 정보 자동 추가
파라미터:
- parking_id: 주차장 이름 또는 주소 (필수)

지역별 제공 정보

정보	서울	경기	기타
기본 정보 (이름, 주소)	✅	✅	✅
총 주차 대수	✅	✅	❌
실시간 주차 가능 대수	✅	❌	❌
운영 시간	✅	✅	❌
요금 정보	✅	✅	❌
업데이트 시간	✅	❌	❌

서울 지역:

실시간 주차 가능 대수 제공
상세 운영 시간 (평일/주말/공휴일)
상세 요금 정보 (기본 요금, 추가 요금, 일일 최대 요금 등)
실시간 정보 업데이트 시간

경기 지역:

총 주차 대수 제공
운영 시간 (평일/토요일/공휴일)
요금 정보 (기본 요금, 추가 요금, 결제 방법)

기타 지역:

기본 주차장 정보만 제공 (이름, 주소, 카테고리)
안내 메시지 표시

지원하는 API

카카오 로컬 API: 전국 주차장 검색 및 주소 변환 (주요 검색 API)
서울 열린데이터: 서울시 실시간 주차 정보 (서울 지역 실시간 정보 추가)
경기데이터드림: 경기도 실시간 주차 정보 (경기 지역 실시간 정보 추가)

사용 예시

예시 1: 서울 지역 주차장 검색

# search_nearby_parking 호출 { "latitude": 37.5665, "longitude": 126.9780, "radius": 1000 } # 응답 예시 { "parkings": [ { "name": "서울시청 주차장", "address": "서울 중구 세종대로 110", "total_spots": 1260, "available_spots": 507, "fee": "교통,지하철 > 지하철역 > 주차장", "distance": 62, "operating_info": { "operating_type": "시간제 운영", "weekday_start": "0000", "weekday_end": "2400", ... }, "fee_info": { "is_paid": "유료", "basic_fee": 430.0, "basic_hours": 5.0, ... }, "update_time": "2025-12-10 10:24:30" } ], "count": 1 }

예시 2: 경기 지역 주차장 검색

# search_nearby_parking 호출 { "latitude": 37.2892, "longitude": 127.0086, "radius": 1000 } # 응답 예시 { "parkings": [ { "name": "화성행궁", "address": "경기도 수원시 팔달구 화성행궁 159", "total_spots": 62, "available_spots": null, "fee": "교통,지하철 > 지하철역 > 주차장", "distance": 0, "operating_info": { "weekday_start": "00:00", "weekday_end": "23:59", ... }, "fee_info": { "is_paid": "유료", "basic_time": 90, "basic_fee": 400, ... } } ], "count": 1 }

예시 3: 기타 지역 주차장 검색

# search_nearby_parking 호출 { "latitude": 35.1631, "longitude": 129.1636, "radius": 1000 } # 응답 예시 { "notice": "해당 지역은 기본 주차장 정보만 제공됩니다. 실시간 정보는 서울 지역에서, 요금 및 운영시간 정보는 서울/경기 지역에서 이용 가능합니다.", "parkings": [ { "name": "해운대역 주차장", "address": "부산 해운대구 우동 1378-95", "total_spots": null, "available_spots": null, "fee": "교통,지하철 > 지하철역 > 주차장", "distance": 0 } ], "count": 1 }

에러 응답 예시

{ "error": "주차장 정보를 불러오는 중 오류가 발생했습니다. 잠시 후 다시 시도해주세요.", "parkings": [] }

상세한 응답 형식은 MCP_RESPONSE_FORMAT.md를 참고하세요.

의존성

fastmcp: MCP 서버 프레임워크
requests: HTTP API 호출
python-dotenv: 환경 변수 관리

Parking Information MCP Server