TMAP MCP

TMAP Open API를 MCP(Model Context Protocol) 서버로 래핑한 프로젝트입니다.

장소 검색, 경로 안내, 지오코딩, 교통 정보 등 27개 tool을 제공합니다.

설치 및 설정

GitHub repo에서 직접 설치:

{
  "mcpServers": {
    "tmap": {
      "command": "npx",
      "args": ["-y", "github:tmobi-internal/tmap-mcp"],
      "env": {
        "TMAP_APP_KEY": "<your-app-key>"
      }
    }
  }
}

또는 로컬 클론:

git clone https://github.com/tmobi-internal/tmap-mcp.git
cd tmap-mcp
npm install

{
  "mcpServers": {
    "tmap": {
      "command": "node",
      "args": ["/path/to/tmap-mcp/dist/index.js"],
      "env": {
        "TMAP_APP_KEY": "<your-app-key>"
      }
    }
  }
}

API Key 발급

1. https://openapi.sk.com 가입
2. 대시보드 → 앱 생성
3. TMAP 상품 구독 신청
4. 발급된 appKey를 TMAP_APP_KEY에 설정

제공 Tools

장소 검색 (POI)

Tool	설명
search_poi	키워드로 장소 검색
get_poi_detail	POI ID로 상세 정보 조회
search_nearby_category	좌표 주변 카테고리별 검색
search_area	읍면동/도로명 검색
get_area_code	지역 분류 코드 조회
search_along_route	경로 반경 내 장소 검색

경로

Tool	설명
get_car_route	자동차 경로 안내
get_pedestrian_route	보행자 경로 안내
get_time_machine_route	타임머신 (미래 출발시간 기반) 경로
calc_distance	직선 거리 계산
get_multi_waypoint_route	다중 경유지 경로 안내 (최대 30개)
optimize_waypoints	경유지 순서 최적화 (최대 10개)
get_route_matrix	다대다 거리/시간 매트릭스
get_road_info	GPS 궤적 → 도로 매칭 (ROAD API)

지오코딩

Tool	설명
geocode	주소 → 좌표 변환
reverse_geocode	좌표 → 주소 변환
convert_coordinates	좌표계 변환 (WGS84, EPSG3857, KATECH 등)
convert_address	구주소 ↔ 신주소 변환
search_postal_code	우편번호 검색
find_nearest_road	가장 가까운 도로 검색
reverse_label	좌표 → 간략 지명 라벨

교통

Tool	설명
get_traffic_info	실시간 교통 정보

기타

Tool	설명
get_static_map	정적 지도 이미지 URL 생성
search_fuel_price_by_poi	POI 기준 좌표를 사용해 주변 유가 검색 (/tmap/oilinfo/aroundOil)
search_fuel_price_by_coord	좌표 주변 유가 검색 (/tmap/oilinfo/aroundOil)
geofence_spatial_search	지오펜스 공간 검색
geofence_area_search	지오펜스 영역 검색
get_congestion	실시간 장소 혼잡도

HTTP 모드 (ChatGPT / 원격 MCP 클라이언트)

stdio 모드 외에 HTTP 서버로도 실행할 수 있습니다. ChatGPT Apps SDK 등 원격 MCP 클라이언트에서 사용할 때 필요합니다.

HTTP 모드에서는 서버에 TMAP_APP_KEY를 설정할 필요가 없습니다. 각 사용자가 Bearer 토큰으로 자신의 TMAP appKey를 전달하면, 서버가 이를 API 호출에 사용합니다.

로컬 실행

# 개발 모드
npm run dev:http

# 프로덕션
npm run build
npm run start:http

기본 포트는 3000이며, PORT 환경변수로 변경 가능합니다.

로컬 테스트 (ngrok)

ChatGPT는 public HTTPS URL이 필요하므로, 로컬 테스트 시 ngrok을 사용합니다.

# 터미널 1: 서버 실행
npm run dev:http

# 터미널 2: ngrok 터널링
ngrok http 3000

ngrok이 출력하는 https://xxxx.ngrok-free.app URL을 ChatGPT 앱 설정에 사용합니다.

Docker 배포

docker build -t tmap-mcp .
docker run -p 3000:3000 tmap-mcp

ChatGPT 연결

1. https://chatgpt.com → 설정 → 앱 → 새 앱 만들기
2. 이름: TMAP
3. MCP 서버 URL: https://<your-domain>/mcp
4. 인증: 액세스 토큰 / API 키 → Bearer → 본인의 TMAP appKey 입력
5. 만들기 → 새 채팅에서 앱 선택 후 사용

환경변수

변수	모드	필수	설명
TMAP_APP_KEY	stdio	✅	TMAP Open API 키
PORT	http		HTTP 서버 포트 (기본: 3000)

AWS Lambda 배포

AWS SAM CLI를 사용하여 Lambda + API Gateway HTTP API로 배포합니다. 서버리스로 운영되며, 요청마다 Bearer 토큰으로 전달된 TMAP appKey를 사용합니다.

구조

ChatGPT → API Gateway HTTP API → Lambda (WebStandardStreamableHTTPServerTransport)
                                    ↓
                              Bearer 토큰에서 appKey 추출 → TMAP Open API 호출

사전 요구사항

• AWS SAM CLI
• AWS 자격 증명 설정 (aws configure 또는 SSO)

배포

# Lambda 번들 빌드 + SAM 빌드 + 배포 (첫 배포 시)
npm run deploy:guided

# 이후 배포
npm run deploy

배포 완료 후 출력되는 API Gateway URL을 ChatGPT 앱의 MCP 서버 URL에 입력합니다.

Outputs
-------
Key                 McpEndpointUrl
Value               https://xxxxxxxxxx.execute-api.ap-northeast-2.amazonaws.com/

ChatGPT 연결 (Lambda)

이미 배포된 서버를 사용하거나, 직접 배포한 URL을 사용할 수 있습니다.

배포된 MCP 서버 URL (사내용):

https://3ek3t0m9tj.execute-api.ap-northeast-2.amazonaws.com/

1. 새 앱 만들기

ChatGPT → 설정 → 앱 → 새 앱 만들기에서 아래와 같이 입력합니다.

• 이름: TMAP
• MCP 서버 URL: 배포된 URL 또는 직접 배포한 URL
• 인증: 액세스 토큰 / API 키
• 헤더 스킴: Bearer

2. TMAP appKey 입력

만들기를 누르면 Bearer 토큰 입력 화면이 나옵니다. 본인의 TMAP appKey를 입력하고 연결합니다.

3. 사용

새 채팅에서 TMAP 앱을 선택하면 장소 검색, 경로 안내 등 28개 tool을 사용할 수 있습니다.