# 🗺️ Atlas GIS MCP 工具集 🚀 > Atlas GIS MCP 工具集由 DataV 团队打造，专为大模型智能处理地理空间数据所设计，包含地理编码、路径规划、空间数据生成与处理、行政区划解析等常见 GIS 工具。 --- ### ⚙️ 前置条件 **开始前请确保你已获取有效 TOKEN，否则无法正常调用工具。** **⚠️ MCP 需要 Node.js v18.x 或更高版本才能正常运行。** 工具调用需要使用 `TOKEN`进行鉴权，可前往 [Atlas 工具官网](https://atlas.datav.aliyun.com/maptool) 页面获取 Token，同时可查看最新的工具列表 ### 🖥️ MCP 服务器配置 Atlas GIS MCP 工具集支持两种连接方式：**stdio 模式**（传统方式）和 **HTTP 模式**（新增支持）。 #### 📡 stdio 模式（推荐用于本地开发） > 💡 **提示：** 按照下方 JSON 配置即可快速集成 Atlas GIS 工具集。 ```json { "mcpServers": { "atlas-gis-tools": { "name": "Atlas GIS 工具集", "type": "stdio", "command": "npx", "args": ["-y", "atlas-tools-mcp-server@latest"], "env": { "TOKEN": "" } } } } ``` #### 🌐 HTTP 模式（推荐用于生产环境和多用户场景） **启动 HTTP 服务器：** ```bash # 使用默认端口 3001 npx -y atlas-tools-mcp-server --http # 使用自定义端口 npx -y atlas-tools-mcp-server --http --port 8080 ``` **MCP 客户端配置：** ```json { "mcpServers": { "atlas-gis-tools": { "name": "Atlas GIS 工具集", "type": "streamableHttp", "url": "http://localhost:3001/mcp?token=" } } } ``` **认证方式：** 1. **URL 查询参数**（推荐）： ``` http://localhost:3001/mcp?token=your_token ``` 2. **HTTP 请求头**： ```bash curl -H "Authorization: Bearer your_token" \ http://localhost:3001/mcp ``` 3. **自定义头部**： ```bash curl -H "X-Atlas-Token: your_token" \ http://localhost:3001/mcp ``` #### 🔄 HTTP 模式 vs stdio 模式 | 特性 | stdio 模式 | HTTP 模式 | | -------------- | ---------------------- | ------------------------------ | | **多用户支持** | ❌ 单用户 | ✅ 多用户并发，认证隔离 | | **部署方式** | 每个客户端启动独立进程 | 单一服务器实例 | | **资源消耗** | 高（多进程） | 低（单进程） | | **网络访问** | 仅本地 | 支持远程访问 | | **负载均衡** | 不支持 | 支持 | | **监控和日志** | 分散 | 集中化 | | **认证方式** | 环境变量 | 多种方式（URL 参数、请求头等） | | **适用场景** | 本地开发、单用户 | 生产环境、多用户、企业部署 | #### 🚀 命令行选项 ```bash npx -y atlas-tools-mcp-server [OPTIONS] 选项： --help, -h 显示帮助信息 --http 启用 HTTP 模式（默认：stdio） --stdio 启用 stdio 模式（默认） --port, -p HTTP 服务器端口（默认：3001） 环境变量： TOKEN, token, ATLAS_TOKEN Atlas API 令牌 PORT HTTP 服务器端口 ``` #### 🔒 多租户支持 **多租户场景示例：** ```bash # 用户 A 使用自己的令牌 curl -X POST "http://localhost:3001/mcp?token=user_a_token" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' # 用户 B 同时使用自己的令牌（不会相互干扰） curl -X POST "http://localhost:3001/mcp?token=user_b_token" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' ``` **迁移指南（从 stdio 到 HTTP）：** 1. **保持向后兼容**：现有的 stdio 配置继续有效 2. **逐步迁移**：可以同时运行 stdio 和 HTTP 模式 3. **配置更新**：将 MCP 客户端配置从 `stdio` 改为 `streamableHttp` 4. **认证调整**：从环境变量改为 URL 参数或请求头 5. **简化配置**：只需要配置 `token` 参数即可 ### 💡 使用案例 **CherryStudio 的实际配置** ![CherryStudio 配置](https://img.alicdn.com/imgextra/i4/O1CN01QSospq24FOUodOae3_!!6000000007361-0-tps-2862-2130.jpg) **搭配百炼 qwen-max-latest 模型使用效果** ![CherryStudio 使用](https://img.alicdn.com/imgextra/i2/O1CN01dInIKN1oniKAS1bNc_!!6000000005270-2-tps-3190-2320.png) ### 📝 使用技巧 可以在 Agent 的系统提示词中添加如下内容，提高工具使用成功率、生成预览工具产出的地理数据链接： ```markdown ## Atlas GIS 工具使用指南 ### 核心原则 1. **工具链式调用**：按数据处理逻辑顺序调用工具，使用前序工具返回的 fileUrl 作为后续输入 2. **结果可视化**：工具返回 fileUrl 时，生成预览链接：https://datav.aliyun.com/portal/school/atlas/area_generator?fileUrl= 3. **简明描述**：为预览链接提供简洁标签，如「省级边界」、「简化地图」、「缓冲区分析」 _具体工具列表及参数请参考工具定义 Schema_ ``` **💡 支持 MCP Prompts 的客户端** 对于支持 MCP Prompts 能力的客户端（如 Claude Desktop、CherryStudio 等），本工具集提供了 `preview-geo` 提示词，包含了完整的工具使用指南。您可以直接调用该提示词，无需手动复制上述内容到系统提示词中。 ### 📚 附：工具列表（持续更新中） **以下是目前支持的主要工具，持续扩充中，欢迎关注！** #### 📍 数据获取类 | 工具名称 | 工具描述 | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 🧭 GeoCoding | **地理编码工具**：用于将地址转换为地理坐标 | | 🗺️ NearbySearch | **周边 POI 搜索工具**：根据中心点坐标，在指定半径范围内搜索周边的 POI 信息，返回 GeoJSON 格式的 POI 数据，包含名称、地址、营业时间、评分等信息 | | 🚗 Routing | **地图路径规划工具**：根据起点、终点和可选途径点规划最佳路线，支持驾车、步行、骑行和电动车模式。返回 GeoJSON 格式的路径数据。**注意**：途径点功能仅在驾车模式下可用，最多支持 16 个途径点 | | ⏰ Isochrone | **等时圈工具**：根据输入的出发点（GCJ-02 坐标，可通过 GeoCoding 工具获取）、出行方式（步行/骑行/驾车）、时间（分钟，支持多个），返回对应的等时圈 GeoJSON 数据。支持反向等时圈模式，所有坐标为 GCJ-02 | | 🏷️ AdcodeToGeojson | **行政区划数据获取工具**：根据中国行政区划代码（必须六位编码，多个用英文逗号分隔）获取对应的 GeoJSON 数据。支持省、市、区级别。若需包含所有子级区域，可在编码后加 `_full`，例如：`330000_full` 表示获取浙江省所有子级区划 | | 📋 GeoJsonPick | **GeoJSON 要素选取工具**：从文件 URL 中按索引范围提取指定要素，支持选择性包含属性字段，最大支持 1000 条记录 | | 📊 BatchGeocoding | **批量地址解析工具**：批量将 CSV 文件中的地址字段解析为经纬度，支持从文件 URL 或直接输入 CSV 数据获取，支持 CSV 和 GeoJSON 输出格式 | #### 🛠️ 数据生成类 | 工具名称 | 工具描述 | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | 🎯 RandomPointsInPolygon | **面内随机点生成工具**：在指定面内随机生成点数据，支持随机（random）分布、均匀（uniform）分布、聚类（cluster）分布 | | 📏 RandomPointsAlongLine | **线周围随机点生成工具**：沿线段周围指定距离内随机生成点数据 | | 📏 LineSegmentGenerator | **线段生成工具**：用于生成两个点的连线，支持多种线段生成策略和参数配置 | | 🕸️ Fishnet | **矩形网格生成工具**：在指定输入要素数据中根据指定边长创建矩形渔网网格 | | 🟡 DotDensity | **点密度地图生成工具**：创建点密度地图，在多边形内部随机分布点来表示数量信息，点的数量与指定字段的数值成比例，常用于人口分布、疾病分布等专题地图 | | ⚫ InterpolatedPointsAlongLine | **线上插值点生成工具**：沿线要素按指定距离间隔生成插值点，支持各种要素类型（非线要素自动转换），距离单位为米 | #### 🧰 数据处理类 | 工具名称 | 工具描述 | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ✂️ Simplify | **几何简化工具**：简化线或面地理要素数据，在保持基本形状的同时显著减少数据大小 | | 🧩 Dissolve | **区域融合工具**：将具有相邻边界的地理要素融合为统一要素，消除内部边界。支持基于属性字段分组融合，主要用于行政区域合并、边界简化等场景。**注意**：用于融合单个数据源内的相邻要素，限制：仅支持线、面要素，要素需具有共享边界 | | ➕ AddField | **字段添加工具**：为地理要素数据添加新字段，支持 JavaScript 表达式计算字段值，可基于现有属性、几何特征进行计算，适用于数据增强、属性计算等场景 | | 🔍 FilterFeatures | **要素筛选工具**：根据 JavaScript 布尔表达式筛选地理要素，支持基于属性值、几何特征进行复杂条件筛选，适用于数据过滤、条件查询等场景 | | ➡️ ConvertToLine | **点/多边形转线工具**：将点或多边形要素转换为线要素，支持按字段分组。 | | ⬛ ConvertToPolygon | **线/点转面工具**：将线或点要素转换为面要素。 | #### 🔄 数据转换类 | 工具名称 | 工具描述 | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 🔧 GeoFormatConverter | **地理数据格式转换工具**：支持将 Shapefile、TopoJSON、KML、CSV 等格式转换为 GeoJSON。自动识别文件格式，CSV 文件需指定经纬度字段名称，可配合 FileUrlContentReader 预览文件内容选择合适字段 | | 🔗 MergeGeoFile | **多文件合并工具**：将多个独立的地理数据文件合并为统一的 GeoJSON 文件。支持 Shapefile、GeoJSON、TopoJSON、KML、CSV 等格式。**注意**：用于合并多个文件，不是融合单个文件内的要素。限制：只有相同几何类型的图层才能合并 | #### 🔧 辅助工具类 | 工具名称 | 工具描述 | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | 📄 FileUrlContentReader | **URL 内容读取工具**：读取指定 URL 文件的前 N 个字节内容，自动检测字符编码并解析文本，常用于预览 CSV 文件头部以识别字段名 | | 🖼️ SvgRender | **地理数据渲染工具**：对单个地理数据文件进行 SVG/PNG 渲染，支持多种样式、符号、标签和主流地图投影，适合快速预览与导出。 | | 🗺️ CreateMap | **地图可视化生成工具**：可综合多个地理数据文件，生成临时地图可视化项目预览，支持多图层、样式配置与交互，适合项目级地图展示。 | #### 🔍 空间分析类 | 工具名称 | 工具描述 | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | 🔵 Buffer | **缓冲区分析工具**：为地理要素数据创建缓冲区，支持点、线、面要素，可指定缓冲区半径和距离单位（米或千米） | | 🏷️ SymbolPoint | **多边形标注点工具**：计算多边形的最佳标注点位置，生成的点位于多边形内部，可用于放置标签、图标或进行空间分析，确保标注内容不会超出多边形边界 | | 🪢 InnerLines | **共享边界提取工具**：提取多边形之间的共享边界，创建不含属性数据的线图层，可用于获取行政区划之间的边界线、分析相邻区域的接壤情况等 | | 🟢 TrackSurface | **轨迹面生成工具**：通过轨迹点生成轨迹面，支持设置半径参数。 | --- ### ❓ 常见问题解答（FAQ） **Q: 工具调用失败怎么办？** > 检查 TOKEN 是否正确并有效、网络是否畅通，以及客户端工具输出的详细报错信息进行排查。 **Q: 如何获取最新工具列表？** > 访问 [Atlas 工具官网](https://atlas.datav.aliyun.com/maptool) 查看最新支持工具。 **Q: 结果数据如何预览？** > 将工具生成的 fileUrl 链接按照规则拼接 `https://datav.aliyun.com/portal/school/atlas/area_generator/?fileUrl=` 即可预览。 **Q: 生成的文件会保存多长时间？** > 工具生成的文件为临时文件，仅保留一天（24 小时）。请在文件过期前及时下载并保存到本地，避免数据丢失。 **Q: HTTP 模式和 stdio 模式有什么区别？** > HTTP 模式支持多用户并发访问，每个用户使用独立的认证信息，适合生产环境；stdio 模式适合本地开发和单用户场景。详见上方对比表格。 **Q: 如何在 HTTP 模式下处理多用户认证？** > HTTP 模式采用请求级认证隔离，每个请求可以通过 URL 参数、Authorization 头或自定义头部传递独立的认证信息，确保用户间的数据安全。 **Q: HTTP 服务器的健康检查端点是什么？** > 访问 `http://localhost:3001/health` 可以检查服务器状态，返回 JSON 格式的健康信息。 **Q: 如何从 stdio 模式迁移到 HTTP 模式？** > 1. 启动 HTTP 服务器：`npx -y atlas-tools-mcp-server --http` > 2. 更新 MCP 客户端配置：将 `type` 从 `stdio` 改为 `streamableHttp`，`url` 设置为 `http://localhost:3001/mcp?token=` > 3. 测试连接确保正常工作后，停止 stdio 模式 如有更多疑问，欢迎通过 [Atlas 工具官网](https://atlas.datav.aliyun.com/maptool) 联系我们！ --- ### 🗒️ Release Notes - 2025-09-15： - 新增 **⏰ Isochrone** 工具，支持等时圈分析，支持多种出行方式和反向等时圈模式。 - 新增 **📏 LineSegmentGenerator** 工具，支持两个点的连线生成，适用于多种线段生成策略。 - 新增 **📊 BatchGeocoding** 工具，支持批量地址解析，将 CSV 文件中的地址字段解析为经纬度，支持多种输入和输出格式。 - 2025-07-21： - 新增 **StreamableHTTP** 模式支持 - 2025-07-10： - 新增 **➡️ ConvertToLine** 工具，支持点/多边形转线，支持分组。 - 新增 **⬛ ConvertToPolygon** 工具，支持线/点转面。 - 新增 **🟢 TrackSurface** 工具，支持轨迹点生成轨迹面，支持设置半径参数。 - 2025-07-08： - 新增 **🖼️ SvgRender** 工具，支持对单个地理数据文件进行 SVG/PNG 渲染与多样样式配置。 - 新增 **🗺️ CreateMap** 工具，支持综合多个地理数据文件生成临时地图可视化项目预览，适合多图层项目级地图展示。