Valhalla MCP Server

瓦尔哈拉MCP服务器

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

示例用法

Claude Desktop Integration

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

特性

目前支持的瓦尔哈拉服务

瓦尔哈拉服务-即将推出

运输方式

• 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 
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 到实际项目位置的路径

1. 重新启动克劳德桌面

测试您的安装

在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文件
• 审查瓦尔哈拉文件