MCP Korea Maps

韩国地图MCP服务器


一个模型上下文协议（MCP）服务器，提供对Kakao Maps和Kakao Mobility API的访问，用于韩国地图服务、地理编码和路线规划。

特性

🗺️ 定位服务

• 地址地理编码：将地址或地名转换为坐标
• 地点搜索：按关键字搜索地点

🛣️ 导航服务

• 路线规划：获取两点之间的方向（坐标或地址）
• 未来发展方向：获取路线规划和出发时间，以进行交通预测
• 多目标优化：优化通往多个目的地的路线

可用工具

1. geocode_address

使用Kakao本地API将地址或地名转换为坐标。

参数：

• place_name （string）：要进行地理编码的地址或地名

例子：

{
  "place_name": "서울시 강남구 테헤란로 152"
}

2. search_places_by_keyword

使用Kakao本地API通过关键字搜索地点。

参数：

• keyword （string）：搜索关键字

例子：

{
  "keyword": "카카오"
}

3. get_directions_by_coordinates

获取两个坐标点之间的方向。

参数：

• origin_longitude （数字）：原点经度
• origin_latitude （数字）：原点纬度
• dest_longitude （数字）：目的地经度
• dest_latitude （数字）：目的地纬度

例子：

{
  "origin_longitude": 127.0357821,
  "origin_latitude": 37.4996954,
  "dest_longitude": 127.1086228,
  "dest_latitude": 37.4012191
}

4. get_directions_by_address

获取两个地址之间的路线。

参数：

• origin_address （string）：源地址
• dest_address （string）：目标地址

例子：

{
  "origin_address": "서울역",
  "dest_address": "강남역"
}

5. get_future_directions

获取未来方向和出发时间，以进行交通预测。

参数：

• origin_longitude （数字）：原点经度
• origin_latitude （数字）：原点纬度
• destination_longitude （数字）：目的地经度
• destination_latitude （数字）：目的地纬度
• departure_time （字符串）：yyyyMMddHHmm格式的出发时间（例如，2025年7月3日09:00为“202507030900”）
• priority （字符串，可选）：路由优先级（“推荐”、“时间”、“距离”）
• alternatives （boolean，可选）：是否返回备选路线
• avoid （字符串，可选）：要避开的道路（逗号分隔：“收费”、“高速公路”、“渡轮”）
• car_type （数字，可选）：车型（0-7）：0=普通车，1=中型车，2=紧凑型车，3-7=商用车
• car_fuel （字符串，可选）：燃料类型（“汽油”、“柴油”、“液化石油气”）
• car_hipass （布尔值，可选）：汽车是否有收费公路的Hi Pass

例子：

{
  "origin_longitude": 127.0357821,
  "origin_latitude": 37.4996954,
  "destination_longitude": 127.1086228,
  "destination_latitude": 37.4012191,
  "departure_time": "202507030900",
  "priority": "TIME",
  "alternatives": true
}

6. optimize_multi_destination_route

优化通往多个目的地的路线。

参数：

• origin_longitude （数字）：原点经度
• origin_latitude （数字）：原点纬度
• destinations （string）：目标数组的JSON字符串
• radius （数字，可选）：搜索半径，单位为米（默认值：5000，最大值：10000）
• priority （字符串，可选）：路由优先级（“时间”或“距离”）

例子：

{
  "origin_longitude": 127.0357821,
  "origin_latitude": 37.4996954,
  "destinations": "[{\"key\":\"dest1\",\"x\":127.1086228,\"y\":37.4012191},{\"key\":\"dest2\",\"x\":127.0357821,\"y\":37.4996954}]",
  "radius": 5000,
  "priority": "TIME"
}

设置

1.获取Kakao API密钥

1. 访问 Kakao开发商
2. 创建应用程序
3. 启用Kakao地图服务
4. 复制REST API密钥

2.环境变量

设置以下环境变量：

export KAKAO_REST_API_KEY="your_kakao_rest_api_key"

可选配置：

# Cache and Rate Limiting
export MCP_KAKAO_CACHE_TTL=3600          # Cache TTL in seconds (default: 3600)
export MCP_KAKAO_RATE_LIMIT_CALLS=10     # Rate limit calls (default: 10)
export MCP_KAKAO_RATE_LIMIT_PERIOD=1     # Rate limit period in seconds (default: 1)
export MCP_KAKAO_CONCURRENCY_LIMIT=5     # Concurrency limit (default: 5)

# Server Configuration (for HTTP transports)
export MCP_TRANSPORT=stdio               # Transport type: stdio, streamable-http, sse
export MCP_HOST=127.0.0.1               # Host address (default: 127.0.0.1)
export MCP_PORT=8000                     # Port number (default: 8000)
export MCP_PATH=/mcp                     # HTTP endpoint path (default: /mcp)
export MCP_LOG_LEVEL=INFO                # Log level (default: INFO)

3.安装依赖项

pip install -e .

运行服务器

STDIO传输（默认）

python -m src.mcp_maps.server

HTTP传输

python -m src.mcp_maps.server --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

服务器发送事件（SSE）

python -m src.mcp_maps.server --transport sse --host 127.0.0.1 --port 8000 --path /mcp

命令行选项

python -m src.mcp_maps.server --help

Options:
  --transport {stdio,streamable-http,sse}
                        Transport protocol to use (default: from environment or stdio)
  --host HOST           Host address for HTTP transports (default: from environment or 127.0.0.1)
  --port PORT           Port for HTTP transports (default: from environment or 8000)
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Log level for the server (default: from environment or INFO)
  --path PATH           Path for HTTP endpoints (default: from environment or /mcp)

与AI工具集成

克劳德桌面

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "korea-maps": {
      "command": "python",
      "args": ["-m", "src.mcp_maps.server"],
      "cwd": "/path/to/mcp-korea-maps",
      "env": {
        "KAKAO_REST_API_KEY": "your_kakao_rest_api_key"
      }
    }
  }
}

光标IDE

1. 安装MCP扩展
2. 配置服务器终结点
3. 设置环境变量

Docker设置

Docker快速入门

1. 设置环境变量：

# Copy the example environment file
cp .env.example .env

# Edit .env file and add your Kakao API key
# KAKAO_REST_API_KEY=your_kakao_rest_api_key_here

1. 使用不同的传输协议运行：

# HTTP transport (default profile)
docker-compose up

# STDIO transport (for MCP client connections)
docker-compose --profile stdio up mcp-maps-stdio

# SSE transport
docker-compose --profile sse up mcp-maps-sse

# Development mode with debug logging
docker-compose --profile dev up mcp-maps-dev

Docker编写服务

HTTP传输（默认）

• 容器名称: korea-maps-mcp-http
• 端口: 8000
• 健康检查：可在 http://localhost:8000/health
• 用例：Web应用程序、REST API

docker-compose up mcp-maps-http

STDIO传输

• 容器名称: korea-maps-mcp-stdio
• 用例：直接MCP客户端连接（Claude Desktop等）

docker-compose --profile stdio up mcp-maps-stdio

SSE 运输

• 容器名称: korea-maps-mcp-sse
• 端口: 8080
• 用例：具有服务器发送事件的实时应用程序

docker-compose --profile sse up mcp-maps-sse

发展模式

• 容器名称: korea-maps-mcp-dev
• 端口: 3000
• 特性：调试日志记录、日志卷装载
• 路径: /api/mcp （与生产不同）

docker-compose --profile dev up mcp-maps-dev

Docker环境变量

所有服务都支持以下环境变量：

# Required
KAKAO_REST_API_KEY=your_api_key

# Optional - Cache and Rate Limiting
MCP_KAKAO_CACHE_TTL=3600          # Cache TTL in seconds
MCP_KAKAO_RATE_LIMIT_CALLS=10     # Rate limit calls per period
MCP_KAKAO_RATE_LIMIT_PERIOD=1     # Rate limit period in seconds
MCP_KAKAO_CONCURRENCY_LIMIT=5     # Max concurrent requests

# Optional - Server Configuration (HTTP/SSE only)
MCP_TRANSPORT=streamable-http     # Transport type
MCP_HOST=0.0.0.0                 # Host address
MCP_PORT=8000                     # Port number
MCP_PATH=/mcp                     # HTTP endpoint path
MCP_LOG_LEVEL=INFO                # Log level

构建自定义Docker镜像

# Build with default settings
docker build -t korea-maps-mcp .

# Build with custom configuration
docker build \
  --build-arg MCP_TRANSPORT=streamable-http \
  --build-arg MCP_PORT=8080 \
  --build-arg MCP_LOG_LEVEL=DEBUG \
  -t korea-maps-mcp:custom .

# Run the custom image
docker run -e KAKAO_REST_API_KEY="your_api_key" -p 8080:8080 korea-maps-mcp:custom

Docker安装脚本

提供了一个方便的设置脚本来简化Docker操作：

# Make the script executable (first time only)
chmod +x docker-setup.sh

# Build the Docker image
./docker-setup.sh build

# Run HTTP service
./docker-setup.sh http

# Run development service
./docker-setup.sh dev

# Test health endpoint
./docker-setup.sh test

# View logs
./docker-setup.sh logs

# Stop all services
./docker-setup.sh stop

# Clean up everything
./docker-setup.sh clean

# Show help
./docker-setup.sh help

脚本会自动执行以下操作：

• 检查 .env 文件并从中创建 .env.example 如果丢失
• 验证 KAKAO_REST_API_KEY 已设置
• 为常见的Docker操作提供简单的命令
• 包括健康检查和日志查看

Docker健康检查

所有HTTP和SSE服务都包括健康检查：

# Check service health
docker-compose ps

# View health check logs
docker-compose logs mcp-maps-http

# Manual health check
curl http://localhost:8000/health

Claude桌面与Docker

对于Claude Desktop与Docker的集成：

{
  "mcpServers": {
    "korea-maps": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/path/to/your/.env",
        "korea-maps-mcp"
      ]
    }
  }
}

API费率限制

服务器包括内置的速率限制和缓存，以遵守Kakao API配额：

• 速率限制：每秒10次呼叫（可配置）
• 缓存：地理编码和搜索结果的1小时TTL
• 并发：限制为5个并发请求
• 重试：针对瞬态错误，采用指数回退自动重试

错误处理

所有工具都包括全面的错误处理：

• 连接错误：使用指数回退自动重试
• API错误：带有状态代码的详细错误消息
• 验证错误：输入验证，并显示有用的错误消息
• 速率限制：自动限制以防止超出配额错误

健康检查

当使用HTTP传输运行时，健康检查端点可用：

curl http://localhost:8000/health

答复：

{
  "status": "healthy",
  "service": "Korea Maps API MCP Server",
  "timestamp": 1234567890.123,
  "api_client": "initialized"
}

示例用法

获取两个地址之间的路线

# This would be called through MCP
{
  "tool": "get_directions_by_address",
  "arguments": {
    "origin_address": "서울역",
    "dest_address": "강남역"
  }
}

查找位置附近的位置

# First geocode an address
{
  "tool": "geocode_address",
  "arguments": {
    "place_name": "명동"
  }
}

# Then search for nearby coffee shops
{
  "tool": "search_places_by_keyword",
  "arguments": {
    "keyword": "카페"
  }
}

规划多站路线

{
  "tool": "optimize_multi_destination_route",
  "arguments": {
    "origin_longitude": 127.0357821,
    "origin_latitude": 37.4996954,
    "destinations": "[{\"key\":\"coffee\",\"x\":127.1086228,\"y\":37.4012191},{\"key\":\"restaurant\",\"x\":127.0270968,\"y\":37.4979414}]",
    "radius": 10000,
    "priority": "TIME"
  }
}

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

贡献

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求