使用说明

MCP地图服务器

一个强大的模型上下文协议（MCP）服务器，通过三个不同的提供商提供全面的映射服务：

谷歌地图API -具有广泛数据的高级功能
开放街道图 -免费、开源的替代方案
API风险范围 -企业空间分析平台

所有提供商都提供具有流式HTTP传输支持和LLM处理功能的统一接口。

🚀 30秒内快速启动

# Install globally
npm install -g mcp-map-server

# Start with your preferred provider:

# Option 1: OpenStreetMap (FREE - No API key needed!)
mcp-map-server --port 3200 --provider osm

# Option 2: Google Maps (Requires API key)
mcp-map-server --port 3200 --apikey "your_google_api_key"

# Option 3: RiskScape (Enterprise)
mcp-map-server --port 3200 --provider riskscape --riskscape-key "your_key"

服务器将在 http://localhost:3200/mcp ✨

🤖 使用克劳德桌面（克劳德代码）

步骤1：启动MCP服务器

首先，使用您首选的提供商启动MCP服务器（请参阅上面的快速入门）。

步骤2：配置Claude桌面

将服务器添加到Claude Desktop配置文件中：

在 macOS 上： ~/Library/Application Support/Claude/claude_desktop_config.json
在Windows上： %APPDATA%\Claude\claude_desktop_config.json
在Linux上： ~/.config/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "maps": {
      "command": "npx",
      "args": [
        "mcp-map-server",
        "--port", "3200",
        "--provider", "osm"
      ]
    }
  }
}

对于不同的提供者，调整args：

// For Google Maps
"args": [
  "mcp-map-server",
  "--port", "3200",
  "--apikey", "your_google_api_key"
]

// For OpenStreetMap (recommended for testing)
"args": [
  "mcp-map-server",
  "--port", "3200",
  "--provider", "osm"
]

// For RiskScape
"args": [
  "mcp-map-server",
  "--port", "3200",
  "--provider", "riskscape",
  "--riskscape-key", "your_riskscape_key"
]

步骤3：重新启动克劳德桌面

更新配置后，重新启动Claude Desktop以加载MCP服务器。

步骤4：在Claude中使用地图工具

配置后，您可以要求Claude使用映射工具：

示例提示：

“搜索纽约时代广场附近的咖啡店”
“获取从旧金山到洛杉矶的路线”
“坐标37.7749，-122.4194处的地址是什么？”
“计算伦敦和巴黎之间的距离”
“查找埃菲尔铁塔2公里范围内评级高于4.0的餐厅”
“获取珠穆朗玛峰大本营的海拔高度”

Claude将自动使用适当的映射工具来回答您的问题。

备选方案：环境变量配置

您还可以在Claude Desktop配置中使用环境变量：

{
  "mcpServers": {
    "maps": {
      "command": "npx",
      "args": ["mcp-map-server"],
      "env": {
        "MCP_SERVER_PORT": "3200",
        "MAP_API_PROVIDER": "osm"
        // Add API keys here if needed:
        // "GOOGLE_MAPS_API_KEY": "your_key",
        // "RISKSCAPE_API_KEY": "your_key"
      }
    }
  }
}

验证连接

重新启动Claude Desktop后，您可以验证MCP服务器是否已连接：

打开克劳德桌面
寻找🔌 右下角的图标
点击查看已连接的MCP服务器
你应该看到7个可用工具的“地图”

如果看不到连接的服务器：

检查Claude Desktop日志是否有错误
确保MCP服务器已全局安装： npm list -g mcp-map-server
验证配置文件JSON语法是否有效
请先尝试手动运行服务器进行测试： mcp-map-server --port 3200 --provider osm

🙌 特别感谢

这个项目得到了社区的捐助。
特别感谢 @junyinnnn 用于帮助添加支持 streamablehttp.

✅ 测试状态

此MCP服务器已通过测试和验证，可与以下设备正常工作：

克劳德桌面
潜水桌面
MCP协议实现

所有工具和功能都通过实际测试确认其功能。

特性

🌍 三重提供商支持：谷歌地图、OpenStreetMap和RiskScape

选择您首选的映射提供商：

谷歌地图 -需要API密钥的高级功能
开放街道图 -无需API密钥的免费开源替代方案
RiskScape -具有高级空间分析功能的企业级API

🗺️ 测绘服务

位置搜索
- 使用可定制的半径和过滤器搜索特定位置附近的地点
- 获取详细的地点信息，包括评级、开放时间和联系方式
地理编码服务
- 将地址转换为坐标（地理编码）
- 将坐标转换为地址（反向地理编码）
距离和方向
- 计算多个出发地和目的地之间的距离和旅行时间
- 获取两点之间的详细转弯方向
- 支持不同的出行方式（驾驶、步行、骑自行车、公交）
高程
- 检索特定位置的高程数据

🚀 高级功能

可流式HTTP传输：具有实时流功能的最新MCP协议
会话管理：具有基于UUID标识的状态会话
多连接支持：处理多个并发客户端连接
回声服务：MCP服务器功能的内置测试工具

快速开始

安装

npm install -g mcp-map-server

启动服务器

MCP服务器可以用三个地图提供程序中的任何一个启动。选择最适合您需求的一个：

选项1:谷歌地图（默认提供程序）

要求： 谷歌地图API密钥(在这里买一个)

# Using command line arguments
mcp-map-server --port 3200 --apikey "your_google_api_key"

# Using environment variables
GOOGLE_MAPS_API_KEY="your_google_api_key" mcp-map-server --port 3200

# Short form
mcp-map-server -p 3200 -k "your_google_api_key"

选项2:OpenStreetMap（免费，无需API密钥）

要求： 无-完全免费使用！

# Using command line arguments
mcp-map-server --port 3200 --provider osm

# Using environment variables
MAP_API_PROVIDER=osm mcp-map-server --port 3200

# Short form
mcp-map-server -p 3200 -r osm

选项3：RiskScape API（企业）

要求： RiskScape API密钥(联系RiskScape)

# Using command line arguments
mcp-map-server --port 3200 --provider riskscape --riskscape-key "your_riskscape_key"

# Using environment variables
MAP_API_PROVIDER=riskscape RISKSCAPE_API_KEY="your_key" mcp-map-server --port 3200

# Short form
mcp-map-server -p 3200 -r riskscape -s "your_riskscape_key"

验证服务器是否正在运行

启动后，服务器将显示：

✅ MCP Server started successfully!
🌐 Endpoint: http://localhost:3200/mcp
📚 Tools: 7 available

命令行选项

mcp-map-server --help

选项	别名	描述	默认值
`--port`	`-p`	在	3200上运行服务器的端口
`--provider`	`-r`	地图提供商（谷歌、osm、riskscape）	谷歌
`--apikey`	`-k`	谷歌地图API密钥	-
`--riskscape-key`	`-s`	RiskScape API密钥	-
`--help`	`-h`	显示帮助信息	-
`--version`	`-v`	显示版本号	-

配置

使用环境变量

创建一个 .env 工作目录中的文件：

对于谷歌地图：

MAP_API_PROVIDER=google
GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
MCP_SERVER_PORT=3200

对于OpenStreetMap：

MAP_API_PROVIDER=osm
MCP_SERVER_PORT=3200
# No API key needed!

对于风险范围：

MAP_API_PROVIDER=riskscape
RISKSCAPE_API_KEY=your_riskscape_api_key_here
MCP_SERVER_PORT=3200

备注：命令行参数始终优先于环境变量。

选择供应商

提供商比较

功能	谷歌地图	OpenStreetMap	RiskScape
需要API密钥	✅ 是	❌ 否	✅ 是的
成本	使用免费套餐按次付费	100%免费	企业定价
最适合	商业应用程序、详细的业务数据	开源项目、注重成本的用户	企业空间分析
地点评分/评论	✅ 广泛	❌ 否	⚠️ 有限
营业时间	✅ 实时	⚠️ 社区提供	⚠️ 有限
实时业务	✅ 是	❌ 否	❌ 没有
全球覆盖	✅ 优秀	✅ 好	⚠️ 区域重点
速率限制	基于计费	合理使用政策	基于API层
空间分析	基本	基本	✅ 高级
API版本	最新	天桥API	v2端点

何时使用每个提供者

需要时使用谷歌地图：

业务信息（评级、评论、小时数）
实时交通数据
街景集成
卓越的地理编码精度
详细的地点信息

需要时使用OpenStreetMap：

完全免费使用
开源兼容性
没有API密钥管理
社区驱动数据
基本映射功能

需要时使用RiskScape：

企业空间分析
风险评估特征
高级路由算法
自定义空间查询
专业支持

可用工具

所有三个提供商都通过统一的接口支持同一组工具：

search_nearby -根据位置搜索附近的地点，可选择按关键字、距离、评级和营业时间进行过滤
get_place_details -获取特定地点的详细信息，包括联系方式、评论、评级和营业时间
地图_地理编码 -将地址或地名转换为地理坐标（纬度和经度）
maps_reverse_geocode -将地理坐标转换为人类可读的地址
地图_距离_矩阵 -计算多个出发地和目的地之间的旅行距离和持续时间
地图_方向 -获取两个位置之间的详细转弯导航方向
地图_立面图 -获取特定地理位置的海拔高度数据

完整设置示例

示例1：使用谷歌地图进行设置

从获取Google Maps API密钥谷歌云控制台
启用所需的API：地点API、地理编码API、方向API、距离矩阵API、高程API

启动服务器：

mcp-map-server --port 3200 --apikey "AIzaSyB..."

示例2：使用OpenStreetMap进行设置

不需要API密钥！

只需启动服务器：

mcp-map-server --port 3200 --provider osm

示例3：使用RiskScape进行设置

从获取API密钥 RiskScape

启动服务器：

mcp-map-server --port 3200 --provider riskscape --riskscape-key "rsk_..."

示例4：使用.env文件（建议用于生产环境）

复制示例环境文件：
```
cp .env.example .env
```

编辑 .env 与您首选的供应商：

MAP_API_PROVIDER=osm  # or 'google' or 'riskscape'
MCP_SERVER_PORT=3200
# Add API keys if needed:
# GOOGLE_MAPS_API_KEY=your_key_here
# RISKSCAPE_API_KEY=your_key_here

启动服务器：
```
mcp-map-server
```

故障排除

常见问题及解决方法

问题：“找不到API密钥”错误

解决方案： 确保您已通过命令行或环境变量提供了API密钥：

# For Google Maps
mcp-map-server --apikey "your_key"
# For RiskScape
mcp-map-server --provider riskscape --riskscape-key "your_key"

问题：端口已在使用中

解决方案： 使用其他端口：

mcp-map-server --port 3201

问题：OpenStreetMap速率限制

解决方案： OpenStreetMap有合理使用限制。如果你打他们，考虑一下：

减少请求频率
将谷歌地图或RiskScape用于高容量应用程序
在应用程序中实现缓存

问题：RiskScape v2端点不工作

解决方案： 请确保您的API密钥可以访问v2终结点。服务器自动使用v2端点以获得更好的性能和功能。

🐳 Docker支持

Docker快速入门

MCP服务器可以使用Docker运行，支持所有三个地图提供商：

构建Docker镜像

# Clone the repository
git clone https://github.com/LeonFNortje/mcp-map-server.git
cd mcp-map-server

# Build the Docker image
docker build -t mcp-map-server .

使用Docker运行

选项1：谷歌地图提供商

docker run -d \
  --name mcp-google-maps \
  -p 3200:3200 \
  -e GOOGLE_MAPS_API_KEY="your_api_key" \
  -e MAP_API_PROVIDER=google \
  mcp-map-server

选项2:OpenStreetMap提供程序（不需要API密钥）

docker run -d \
  --name mcp-osm \
  -p 3200:3200 \
  -e MAP_API_PROVIDER=osm \
  mcp-map-server \
  --port 3200 --provider osm

选项3:RiskScape提供商

docker run -d \
  --name mcp-riskscape \
  -p 3200:3200 \
  -e MAP_API_PROVIDER=riskscape \
  -e RISKSCAPE_API_KEY="your_api_key" \
  mcp-map-server \
  --port 3200 --provider riskscape

使用Docker Compose

为了便于管理，请使用Docker Compose运行任何或所有提供程序：

创建一个 .env 文件 使用API密钥：

GOOGLE_MAPS_API_KEY=your_google_api_key
RISKSCAPE_API_KEY=your_riskscape_api_key

启动特定服务：

# Start only Google Maps server
docker-compose up -d mcp-google-maps

# Start only OpenStreetMap server (no API key needed)
docker-compose up -d mcp-openstreetmap

# Start only RiskScape server
docker-compose up -d mcp-riskscape

# Or start all services at once (on different ports)
docker-compose up -d

docker-compose.yml配置：

谷歌地图：端口3200
开放街道图：端口3201
RiskScape：端口3202

检查服务状态：

docker-compose ps
docker-compose logs mcp-google-maps

停止服务：

docker-compose down

Docker功能

多阶段构建 优化图像大小（~150MB）
非root用户 增强安全性
健康检查 用于集装箱自动监控
环境变量支持 便于配置
三家供应商 支持简单的环境变量切换

Docker与克劳德桌面

要在Claude Desktop中使用Docker容器，请更新您的配置：

{
  "mcpServers": {
    "maps": {
      "command": "docker",
      "args": [
        "run", "--rm",
        "-e", "MAP_API_PROVIDER=osm",
        "mcp-map-server",
        "--port", "3200",
        "--provider", "osm"
      ]
    }
  }
}

发展

地方发展

# Clone the repository
git clone https://github.com/LeonFNortje/mcp-map-server.git
cd mcp-map-server

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your preferred provider and API keys

# Build the project
npm run build

# Start the server
npm start

# Or run in development mode
npm run dev

项目结构

src/
├── cli.ts                    # Main CLI entry point
├── config.ts                 # Server configuration
├── index.ts                  # Package exports
├── core/
│   └── BaseMcpServer.ts     # Base MCP server with streamable HTTP
├── services/
│   ├── PlacesSearcher.ts    # Service layer with provider switching
│   ├── toolclass.ts         # Google Maps API client
│   ├── OpenStreetMapTools.ts # OpenStreetMap API client
│   └── RiskScapeTools.ts    # RiskScape API client
└── tools/
    └── maps/                # Map service tools
        ├── searchNearby.ts  # Search nearby places
        ├── placeDetails.ts  # Place details
        ├── geocode.ts       # Geocoding
        ├── reverseGeocode.ts # Reverse geocoding
        ├── distanceMatrix.ts # Distance matrix
        ├── directions.ts    # Directions
        └── elevation.ts     # Elevation data

技术栈

TypeScript -类型安全开发
Node.js -运行时环境
谷歌地图服务JS -谷歌地图API集成
模型上下文协议SDK -MCP协议实现
Express.js -HTTP服务器框架
萨德 -架构验证

安全考虑

为了安全起见，API密钥在服务器端进行处理
DNS重新绑定保护可用于生产
使用Zod模式进行输入验证
错误处理和日志

许可证

麻省理工学院

贡献

欢迎社区参与和贡献！以下是您如何做出贡献：

⭐️ 如果你觉得这个项目有帮助，就给它标上星号
🐛 提交问题：报告错误或提供建议
🔧 创建拉取请求：提交代码改进
📖 文档：帮助改进文档

联系

如果您有任何问题或建议，请随时联系：

📧 电子邮件： lnortje@gmail.com
💻 github： LeonFNortje
🤝 合作：欢迎洽谈项目合作
📚 技术指导：真诚欢迎您的建议和指导

更新日志

v0.2.0（最新）-三重提供商支持

新添加RiskScape API作为第三个提供程序选项
新实现了所有RiskScape v2端点以获得更好的性能
新添加 --riskscape-key RiskScape身份验证的CLI选项
改进： 增强的README，为所有提供商提供全面的设置说明
补充： 提供商比较指南和故障排除部分
补充： 在risk-API-uses.md中完成RiskScape API文档
特点： 全面的三重提供商支持：谷歌地图、OpenStreetMap和RiskScape

v0.1.0-OpenStreetMap集成

新添加OpenStreetMap作为谷歌地图的免费替代品
新通过以下方式实现提供商切换 --provider CLI选项
改变： 将默认端口从3000更新为3200，以避免冲突
固定的： 将所有错误信息从中文翻译成英文
补充： 在maps-API-uses.md中提供全面的API文档
特点： 使用OpenStreetMap提供程序时不需要API密钥
固定的： 解决了飞行中和glob包的npm弃用警告

v0.0.5

添加了流式HTTP传输支持
改进了带有表情符号指示器的CLI界面
增强的错误处理和日志记录
为LLM集成添加了全面的工具描述
更新到最新的MCP SDK版本