geolens-mcp Skill 技能

技能简介

geolens-mcp 是一款由 GeoLens 官方提供的 Apache-2.0 开源 Model Context Protocol（MCP）服务器，专为 AI 编码代理设计，让代理能够发现数据集、检查数据 schema、查询地理特征（features）和地图，以及在 GeoLens 实例上执行只读 SQL 查询。它支持 Claude Code、Cursor、Codex 等主流 AI 编码代理，接入后代理可在开发会话中直接查询地理信息，无需手动在 GeoLens 网页界面中操作。

核心能力

1. 数据集发现：AI 代理可以通过 MCP 工具列出 GeoLens 实例中所有可用的数据集，按名称、标签或权限过滤，快速找到所需数据源。
2. Schema 检查：通过 inspect_schema 工具查看数据集中的字段结构，帮助代理了解数据格式后再编写查询。
3. 只读 SQL 查询：通过 query 工具向 GeoLens 实例发送 SQL 查询，服务器端强制 READ ONLY 模式执行，无法写入或修改任何数据。
4. 地图和要素读取：代理可以读取数据集的地图配置（Map）和地理要素（Features），用于理解数据的空间可视化方式。
5. 权限感知：查询权限与 API Key 绑定——持有 AI-chat 权限的 read_only API key 可以执行 query，无 key 时只能访问公开数据。
6. 跨实例通用：兼容任何符合 GeoLens API 规范的实例（公共或私有部署），不限定特定的 GeoLens 服务商。
7. MCP 工具生态兼容：以标准 MCP 服务器实现，天然融入 Claude Code、Cursor、Windsurf、Zed 等编辑器的 MCP 工具生态。

安装配置

1. pip 安装（Python 3.10+）：

   pip install geolens-mcp

   或使用 uvx 无安装运行：

   uvx geolens-mcp

2. 配置环境变量：

   export GEOLENS_INSTANCE=https://geolens.example.com
   export GEOLENS_API_KEY=your_api_key_here

   GEOLENS_INSTANCE 的 /api 后缀会自动追加。

3. 编辑器 MCP 配置：在 Claude Code 的 .mcp.json 或其他 MCP 客户端中添加服务器条目，指定命令为 geolens-mcp 并配置环境变量。

4. 公共数据免配置：若只需访问公开数据，可不设置 GEOLENS_API_KEY，直接连接公开 GeoLens 实例即可。

使用步骤

1. 连接 GeoLens 实例：配置 GEOLENS_INSTANCE 环境变量后启动 geolens-mcp 服务器，编辑器 MCP 客户端自动建立 STDIO 连接。

2. 发现可用数据集：使用 list_datasets 工具获取实例上所有数据集列表，包含数据集名称、描述、标签和可见范围信息。

3. 检查目标 Schema：在编写查询前，使用 inspect_schema 工具查看目标数据集的字段结构，确保查询字段名和类型正确。

4. 执行只读查询：使用 query 工具发送 SQL 查询语句，服务器在 GeoLens 的 READ ONLY SQL 沙箱中执行，结果以 JSON 格式返回。

5. 读取地图和要素：使用 get_map 读取地图配置，查看数据可视化方式；使用 get_features 按空间范围或属性条件读取地理要素列表。

适用场景

1. AI 编程中的地理数据查询：开发者使用 AI 编码代理构建基于地理位置的应用时，代理可以直接查询 GeoLens 数据集，无需切换到 GeoLens 网页界面。
2. 数据分析与探索：数据科学家在 Jupyter 或 VS Code 中使用 AI 代理辅助数据分析时，通过 MCP 接口探索 GeoLens 中的地理空间数据。
3. 空间应用原型开发：AI 代理基于 GeoLens 数据快速生成原型代码（Python、JavaScript 等），用于地理位置展示、热力图渲染、空间查询等功能。
4. 多源数据整合：将 GeoLens 地理数据与其他业务数据源结合，AI 代理通过 MCP 查询地理位置信息后与业务数据 join。
5. 私有 GeoLens 部署集成：企业自建 GeoLens 实例管理内部地理资产，开发者通过 geolens-mcp 在 IDE 中直接访问私有数据。

适用人群

• 使用 Claude Code、Cursor、Windsurf、Codex 等 AI 编码代理的前端/全栈开发者
• 数据工程师和数据科学家（处理地理空间数据的从业者）
• GIS（地理信息系统）开发者和分析师
• 在应用开发中需要集成地理数据的 AI 工作流使用者

工作原理

geolens-mcp 是一个标准 MCP 服务器，通过 STDIO 与 AI 编码代理通信。它封装了 GeoLens REST API 的核心功能，以 MCP 工具的形式暴露：

• list_datasets：GET /api/datasets，返回数据集清单
• inspect_schema：GET /api/datasets/{id}/schema，返回字段结构
• query：POST /api/query，SQL 在 GeoLens 服务器端 READ ONLY 模式执行
• get_features：GET /api/features，按空间范围或属性过滤读取要素

所有调用遵循 MCP 协议规范，工具调用通过 JSON-RPC 2.0 序列化传输，不需要维护 WebSocket 长连接或特殊网络配置。

官方链接

• PyPI 主页：https://pypi.org/project/geolens-mcp/
• GitHub 仓库（geolens 主项目 245 星）：https://github.com/geolens-io/geolens
• GeoLens 官方文档：https://docs.getgeolens.com/
• MCP 协议规范：https://modelcontextprotocol.io