AI导哈

地图路由服务

Valhalla MCP Server是一个模型上下文协议服务器，提供Claude Desktop与Valhalla Open-Street-Map路由引擎的无缝集成，支持专业路由和等时线功能。

  • by aatakansalar
  • TypeScript
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 aatakansalar/valhalla-mcp

使用说明

瓦尔哈拉MCP服务器

模型上下文协议（MCP）服务器，提供Claude Desktop和瓦尔哈拉开放街道地图路由引擎之间的无缝集成。直接从您的AI对话中访问专业路由和等时功能，而无需复杂的API。

示例用法

Claude Desktop显示两点之间的路线计算，并附有Valhalla MCP服务器的详细GeoJSON响应

特性

目前支持的瓦尔哈拉服务

MCP工具/资源 瓦尔哈拉服务 描述
route 工具 /route 单一来源→ 目的地路由选择
isochrone 工具 /isochrone 显示可达区域的行程时间多边形
health 资源 /status 服务器状态和版本信息
tile 资源 /tile/{z}/{x}/{y} 用于客户端渲染的矢量图块

瓦尔哈拉服务-即将推出

服务 描述 用例
矩阵 多个出发地/目的地的距离/时间矩阵 交付优化、物流规划
地图匹配 将GPS坐标与道路网络匹配 GPS轨迹清理、路线校正
海拔 沿线或各点的海拔剖面图 徒步路线，难度分析
扩张 图遍历可视化 网络分析、可达性研究
定位 关于节点和边的详细元数据 地址地理编码、道路属性
质心 来自多个位置的最佳收敛点 汇合点优化
优化路线 有约束的多站交付路线 物流、交付服务

运输方式

  • auto -车辆路线
  • bicycle -自行车路线
  • pedestrian -步行路线
  • taxi -出租车路线
  • bus -公共交通路线

快速开始

先决条件

  • Node.js 18+
  • 克劳德桌面
  • NPM或Yarn包管理器

选项1：本地瓦尔哈拉服务器

用于生产或自定义数据集：

# Prerequisites: Docker and Docker Compose
./start-mcp.sh

此脚本将：

  • 构建MCP服务器
  • 从摩纳哥OSM数据开始本地瓦尔哈拉
  • 等待服务准备就绪
  • 运行集成测试
  • 提供Claude桌面配置

选项2：使用现有的Valhalla服务器

如果您已经在其他地方运行了Valhalla服务器：

# Clone and setup
git clone <repository-url>
cd valhalla-mcp
npm install
npm run build

# Configure environment variables
cp env.example .env
# Edit .env file and set VALHALLA_BASE_URL=http://your-valhalla-server:8002

Claude桌面集成

  1. 打开克劳德桌面设置
  2. 添加到MCP配置中：

对于演示API（推荐用于测试）：

{
  "mcpServers": {
    "valhalla-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/YOUR/PATH/TO/valhalla-mcp",
      "env": {
        "VALHALLA_BASE_URL": "https://valhalla1.openstreetmap.de"
      }
    }
  }
}

对于本地Valhalla服务器：

{
  "mcpServers": {
    "valhalla-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/YOUR/PATH/TO/valhalla-mcp",
      "env": {
        "VALHALLA_BASE_URL": "http://localhost:8002"
      }
    }
  }
}

  1. 更新 cwd 到实际项目位置的路径

  2. 重新启动克劳德桌面

测试您的安装

在Claude Desktop中尝试以下命令以验证一切正常：

基本路线：

  • “计算从摩纳哥城到蒙特卡洛的路线”
  • “获取从43.7384,7.4246到43.7396,7.4263的行车路线”
  • “计算从43.7350,7.4200到43.7450,7.4300的自行车路线”

行程时间分析：

  • “显示距离摩纳哥中心10分钟车程的等时线”
  • “从43.7311,7.4197生成15分钟自行车行程多边形”

您应该收到详细的GeoJSON回复，其中包含路线几何形状和旅行统计数据！

发展模式

对于自动重新加载的开发：

npm run dev

配置

环境变量

服务器使用环境变量进行配置。创建一个 .env 模板中的文件：

cp env.example .env

可用环境变量：

  • VALHALLA_BASE_URL -Valhalla服务的基本URL（默认值：http://localhost:8002)
  • DEBUG -启用调试日志记录（默认值：false）
  • LOG_LEVEL -日志级别：错误、警告、信息、调试（默认值：信息）
  • MCP_SERVER_NAME -MCP服务器名称（默认：瓦尔哈拉MCP服务器）
  • MCP_SERVER_VERSION -MCP服务器版本（默认：0.1.0）

常见的瓦尔哈拉终点：

  • http://localhost:8002 -本地Docker实例（推荐）
  • https://valhalla1.openstreetmap.de -公开演示API(✅ 测试和工作）
  • https://your-server.com:8002 -自定义部署

注： 主演示URL https://valhalla.openstreetmap.de 提供web界面。使用 https://valhalla1.openstreetmap.de 用于API访问。

Docker部署

可以使用Docker Compose部署完整的堆栈：

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f valhalla-mcp

# Stop services
docker-compose down

使用示例

路线计算

请求两点之间的路线：

{
  "tool": "route",
  "arguments": {
    "origin": { "lat": 52.5200, "lon": 13.4050 },
    "destination": { "lat": 52.5170, "lon": 13.3888 },
    "mode": "bicycle",
    "alternatives": 2,
    "units": "kilometers"
  }
}

响应包括GeoJSON LineString，其中包含路线几何形状和汇总统计信息：

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[13.4050, 52.5200], [13.3888, 52.5170]]
    },
    "properties": {
      "distance_km": 2.1,
      "duration_seconds": 420,
      "duration_minutes": 7,
      "mode": "bicycle"
    }
  }]
}

等时线生成

生成15分钟行程时间多边形：

{
  "tool": "isochrone",
  "arguments": {
    "origin": { "lat": 52.5200, "lon": 13.4050 },
    "minutes": 15,
    "mode": "pedestrian"
  }
}

健康检查

访问服务器运行状况信息：

{
  "resource": "health://status"
}

与MCP客户端集成

克劳德桌面

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "valhalla": {
      "command": "node",
      "args": ["/path/to/valhalla-mcp/dist/index.js"],
      "env": {
        "VALHALLA_BASE_URL": "https://valhalla1.openstreetmap.de"
      }
    }
  }
}

注： Claude Desktop配置覆盖中的环境变量 .env 文件值。

其他MCP客户端

服务器实现了标准的MCP协议，并与任何兼容的客户端一起工作。使用 stdio 交通促进当地融合。

建筑

┌─────────────────┐     MCP Protocol     ┌─────────────────┐
│   MCP Client    │ ◄─────────────────► │ Valhalla MCP    │
│ (Claude, etc.)  │    (stdio/HTTP)      │     Server      │
└─────────────────┘                      └─────────┬───────┘
                                                   │ HTTP REST
                                         ┌─────────▼───────┐
                                         │   Valhalla      │
                                         │  Routing Engine │
                                         └─────────────────┘

发展

安装

# Install dependencies
npm install

# Build the project
npm run build

关键依赖关系：

  • @modelcontextprotocol/sdk -官方MCP SDK
  • axios -用于Valhalla API调用的HTTP客户端
  • zod -运行时类型验证
  • geojson -GeoJSON类型定义
  • dotenv -环境变量管理

测试

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

类型检查

该项目使用严格的TypeScript配置：

# Type check
npx tsc --noEmit

演出

  • 路线计算：<200ms（本地瓦尔哈拉实例）
  • 等时线生成：<300ms
  • 瓷砖服务：<30ms
  • 健康检查：<5ms

性能取决于瓦尔哈拉配置和可用的OSM数据。

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加测试
  5. 提交拉取请求

许可证

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

致谢

对于问题和疑问：

  • 在GitHub上打开一个问题
  • 检查 MCP文件
  • 审查瓦尔哈拉文件

相关 MCP