목록으로
기술

Koog를 사용한 Google 지도 MCP: Kotlin 노트북의 0에서 고도까지

·3분 읽기
#Koog#JetBrains#AI Agent#Kotlin#Java#JVM

원문: Koog Documentation — GoogleMapsMcp 이 글은 Koog 공식 문서의 GoogleMapsMcp 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

Koog를 사용한 Google 지도 MCP: Kotlin 노트북의 0에서 고도까지

:material-github: Open on GitHub{ .md-button .md-button--기본 } :material-download: Download .ipynb{ .md-버튼 }

이 짧은 블로그 스타일 연습에서는 Koog를 Google 지도용 MCP(Model Context Protocol) 서버에 연결합니다. Docker로 서버를 가동하고, 사용 가능한 도구를 검색하고, AI 에이전트가 주소를 지오코딩하고 고도를 가져오도록 할 것입니다. 이 모든 작업이 Kotlin Notebook에서 이루어집니다.

결국에는 워크플로우나 문서에 넣을 수 있는 재현 가능한 엔드투엔드 예제를 얻게 됩니다.

1%useLatestDescriptors2%use koog3

전제 조건

아래 셀을 실행하기 전에 다음 사항을 확인하세요.

  • Docker가 설치되어 실행 중입니다.
  • 환경 변수로 내보낸 유효한 Google Maps API 키: GOOGLE_MAPS_API_KEY
  • OPENAI_API_KEY로 내보낸 OpenAI API 키

다음과 같이 셸에서 설정할 수 있습니다(macOS/Linux 예).

1export GOOGLE_MAPS_API_KEY="<your-key>"2export OPENAI_API_KEY="<your-openai-key>"
1// Get the API key from environment variables2val googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY") ?: error("GOOGLE_MAPS_API_KEY environment variable not set")3val openAIApiToken = System.getenv("OPENAI_API_KEY") ?: error("OPENAI_API_KEY environment variable not set")4

Google 지도 MCP 서버 시작(Docker)

공식 mcp/google-maps 이미지를 사용하겠습니다. 컨테이너는 MCP를 통해 maps_geocode 및 maps_elevation와 같은 도구를 노출합니다. 환경 변수를 통해 API 키를 전달하고 노트북이 stdio를 통해 통신할 수 있도록 첨부된 키를 실행합니다.

1// Start the Docker container with the Google Maps MCP server2val process = ProcessBuilder(3    "docker",4    "run",5    "-i",6    "-e",7    "GOOGLE_MAPS_API_KEY=$googleMapsApiKey",8    "mcp/google-maps"9).start()10

McpToolRegistry를 통해 도구 검색

Koog는 stdio를 통해 MCP 서버에 연결할 수 있습니다. 여기에서는 실행 중인 프로세스에서 도구 레지스트리를 생성하고 검색된 도구와 해당 설명자를 인쇄합니다.

1val toolRegistry = McpToolRegistryProvider.fromTransport(2    transport = McpToolRegistryProvider.defaultStdioTransport(process)3)4toolRegistry.tools.forEach {5    println(it.name)6    println(it.descriptor)7}8

OpenAI로 AI 에이전트 구축

다음으로 OpenAI 실행기와 모델이 지원하는 간단한 에이전트를 구성합니다. 에이전트는 방금 생성한 레지스트리를 통해 MCP 서버에 의해 노출된 도구를 호출할 수 있습니다.

1val agent = AIAgent(2    executor = simpleOpenAIExecutor(openAIApiToken),3    llmModel = OpenAIModels.Chat.GPT4o,4    toolRegistry = toolRegistry,5)6

고도 요청: 먼저 지오코딩한 후 고도 요청

에이전트에게 뮌헨에 있는 JetBrains 사무실의 고도를 찾으라는 메시지를 표시합니다. 이 지침은 에이전트에게 사용 가능한 도구만 사용하고 작업에 어떤 도구를 선호할지 명시적으로 지시합니다.

1import kotlinx.coroutines.runBlocking23val request = "Get elevation of the Jetbrains Office in Munich, Germany?"4runBlocking {5    agent.run(6        request +7            "You can only call tools. Get it by calling maps_geocode and maps_elevation tools."8    )9}10

정리하다

완료되면 Docker 프로세스를 중지하여 백그라운드에서 아무것도 실행되지 않도록 하세요.

1process.destroy()2

문제 해결 및 다음 단계

  • 컨테이너가 시작되지 않으면 Docker가 실행 중이고 GOOGLE_MAPS_API_KEY이 유효한지 확인하세요.
  • 에이전트가 도구를 호출할 수 없는 경우 검색 셀을 다시 실행하여 도구 레지스트리가 채워졌는지 확인하세요.
  • 사용 가능한 Google 지도 도구를 사용하여 경로 계획이나 장소 검색과 같은 다른 메시지를 시도해 보세요.

다음으로, 여러 MCP 서버(예: 웹 자동화용 Playwright + Google 지도) 구성을 고려하고 Koog가 더 풍부한 작업을 위해 도구 사용을 조정하도록 하세요.

#Koog#JetBrains#AI Agent#Kotlin#Java#JVM