🗺️ Atlas GIS MCP 工具集 🚀

Atlas GIS MCP 工具集由 DataV 团队打造，专为大模型智能处理地理空间数据所设计，包含地理编码、路径规划、空间数据生成与处理、行政区划解析等常见 GIS 工具。

⚙️ 前置条件

开始前请确保你已获取有效 TOKEN，否则无法正常调用工具。

⚠️ MCP 需要 Node.js v18.x 或更高版本才能正常运行。

工具调用需要使用 TOKEN进行鉴权，可前往 Atlas 工具官网 页面获取 Token，同时可查看最新的工具列表

🖥️ MCP 服务器配置

Atlas GIS MCP 工具集支持两种连接方式：stdio 模式（传统方式）和 HTTP 模式（新增支持）。

📡 stdio 模式（推荐用于本地开发）

💡 提示： 按照下方 JSON 配置即可快速集成 Atlas GIS 工具集。

{
  "mcpServers": {
    "atlas-gis-tools": {
      "name": "Atlas GIS 工具集",
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "atlas-tools-mcp-server@latest"],
      "env": {
        "TOKEN": "<YOUR_TOKEN_HERE>"
      }
    }
  }
}

🌐 HTTP 模式（推荐用于生产环境和多用户场景）

启动 HTTP 服务器：

# 使用默认端口 3001
npx -y atlas-tools-mcp-server --http

# 使用自定义端口
npx -y atlas-tools-mcp-server --http --port 8080

MCP 客户端配置：

{
  "mcpServers": {
    "atlas-gis-tools": {
      "name": "Atlas GIS 工具集",
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp?token=<YOUR_TOKEN_HERE>"
    }
  }
}

认证方式：

1. URL 查询参数（推荐）：

   http://localhost:3001/mcp?token=your_token

2. HTTP 请求头：

   curl -H "Authorization: Bearer your_token" \
        http://localhost:3001/mcp

3. 自定义头部：

   curl -H "X-Atlas-Token: your_token" \
        http://localhost:3001/mcp

🔄 HTTP 模式 vs stdio 模式

| 特性 | stdio 模式 | HTTP 模式 | | -------------- | ---------------------- | ------------------------------ | | 多用户支持 | ❌ 单用户 | ✅ 多用户并发，认证隔离 | | 部署方式 | 每个客户端启动独立进程 | 单一服务器实例 | | 资源消耗 | 高（多进程） | 低（单进程） | | 网络访问 | 仅本地 | 支持远程访问 | | 负载均衡 | 不支持 | 支持 | | 监控和日志 | 分散 | 集中化 | | 认证方式 | 环境变量 | 多种方式（URL 参数、请求头等） | | 适用场景 | 本地开发、单用户 | 生产环境、多用户、企业部署 |

🚀 命令行选项

npx -y atlas-tools-mcp-server [OPTIONS]

选项：
  --help, -h              显示帮助信息
  --http                  启用 HTTP 模式（默认：stdio）
  --stdio                 启用 stdio 模式（默认）
  --port, -p <number>     HTTP 服务器端口（默认：3001）

环境变量：
  TOKEN, token, ATLAS_TOKEN    Atlas API 令牌
  PORT                        HTTP 服务器端口

🔒 多租户支持

多租户场景示例：

# 用户 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 的实际配置

搭配百炼 qwen-max-latest 模型使用效果

📝 使用技巧

可以在 Agent 的系统提示词中添加如下内容，提高工具使用成功率、生成预览工具产出的地理数据链接：

## Atlas GIS 工具使用指南

### 核心原则

1. **工具链式调用**：按数据处理逻辑顺序调用工具，使用前序工具返回的 fileUrl 作为后续输入
2. **结果可视化**：工具返回 fileUrl 时，生成预览链接：https://datav.aliyun.com/portal/school/atlas/area_generator?fileUrl=<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 工具官网 查看最新支持工具。

Q: 结果数据如何预览？

将工具生成的 fileUrl 链接按照规则拼接 https://datav.aliyun.com/portal/school/atlas/area_generator/?fileUrl=<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=<YOUR_TOKEN>
3. 测试连接确保正常工作后，停止 stdio 模式

如有更多疑问，欢迎通过 Atlas 工具官网 联系我们！

🗒️ 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 工具，支持综合多个地理数据文件生成临时地图可视化项目预览，适合多图层项目级地图展示。