# GeoSource MCP 🌍

<p align="center">
  <b>A Model Context Protocol (MCP) Server for Global GIS Services & Spatial Layers</b><br>
  <b>面向全球 GIS 空间服务与图层目录的 MCP 标准数据接口</b>
</p>

<p align="center">
  <a href="#english">English</a> •
  <a href="#chinese">中文说明</a>
</p>

<p align="center">
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue.svg" alt="MCP"></a>
  <a href="https://glama.ai/mcp/servers"><img src="https://img.shields.io/badge/Glama-Approved-10b981.svg" alt="Glama Approved"></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10+-brightgreen.svg" alt="Python"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"></a>
  <img src="https://img.shields.io/badge/Services-2%2C198%2B-blue.svg" alt="Services">
  <img src="https://img.shields.io/badge/Layers-1%2C561%2B-green.svg" alt="Layers">
</p>

---

<a name="english"></a>
## 🌐 English

### What is GeoSource MCP?
**GeoSource MCP** is a standardized data access server implementing the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). It connects AI environments (such as Claude Desktop, Cursor, and other MCP clients) directly with a verified database of **2,198+ global GIS spatial services** and **1,561+ spatial layers**.

> **Registry Status**: Officially audited, approved, and listed on the [Glama MCP Registry](https://glama.ai/mcp/servers).

### Why is this needed?
When developing GIS applications or writing spatial scripts, AI assistants typically do not have direct access to up-to-date, public GIS service endpoints. This often leads to incomplete answers, outdated references, or hallucinated URLs. 

GeoSource MCP connects directly to an indexed SQLite database (`gis_services.db`), providing AI models with low-latency (sub-0.05s) tools to discover real public endpoints (including OGC WMS, WFS, WMTS, XYZ Tiles, ArcGIS REST, and STAC).

### Key Highlights
- **Sub-0.05s Response Time**: Local SQLite index provides millisecond-level search without network roundtrips.
- **99% Token Reduction**: Fetches only matching records (200 ~ 500 tokens per search) instead of injecting megabytes of raw spreadsheets into the prompt.
- **Hallucination-Free**: Ensures endpoints, layer names, and authentication requirements passed to the code are 100% verified.
- **Two-Way Maintenance**: Supports syncing from Excel files, and allows AI models to update broken URLs dynamically via built-in tools.

### Database Contents
- **2,198+ Master Services**: Covers national and regional mapping agencies, open data portals, elevation/DEM providers, satellite imagery, and environmental datasets.
- **1,561+ Layer Details**: Specific sub-layer identifiers for direct map integration.
- **50+ Attributes per Service**: Protocol, country, category, authentication type, API key requirements, format, and commercial terms.

### Available MCP Tools

| Tool | Parameters | Purpose |
| :--- | :--- | :--- |
| `search_gis_services` | `keyword`, `country`, `protocol`, `category`, `is_free`, `need_no_key`, `limit` | Searches services based on multiple filtering criteria. |
| `get_service_detail` | `service_id` | Retrieves full metadata and child layers for a given service ID. |
| `list_categories_and_stats` | *(None)* | Returns summary statistics of categories, protocols, and geographic coverage. |
| `query_gis_sql` | `query` | Runs read-only `SELECT` SQL queries against the local SQLite database. |
| `update_service_status` | `service_id`, `new_url`, `status`, `notes` | Updates service availability, URLs, or notes in the database. |

### Getting Started

#### 1. Requirements & Setup
Ensure Python 3.10+ is installed:
```bash
git clone https://github.com/Wukeeeeee/GeoSource-MCP.git
cd GeoSource-MCP
pip install mcp
```

#### 2. Local Test
Verify database connectivity and query performance:
```bash
python server.py --test
```

#### 3. Client Configuration

##### Claude Desktop
Add the following to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "geosource": {
      "command": "python",
      "args": ["<FULL_PATH_TO_GEOSOURCE>/server.py"]
    }
  }
}
```

##### Cursor / IDEs
In your MCP settings, configure a new stdio server:
- **Command**: `python`
- **Args**: `<FULL_PATH_TO_GEOSOURCE>/server.py`

---

<a name="chinese"></a>
## 🇨🇳 中文说明

### 项目简介
**GeoSource MCP** 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 标准的数据服务程序。它让各类支持 MCP 的 AI 工具（如 Claude Desktop、Cursor 等）能够直接连接并检索本地结构化索引的 **2,198+ 个全球真实 GIS 空间服务** 与 **1,561+ 个地图图层**。

> **生态认证**：本项目已通过全球领先的 [Glama MCP Registry](https://glama.ai/mcp/servers) 自动化构建、运行与代码安全审计，已正式审核通过（Approved）上线收录。

### 解决什么问题？
在编写地图代码（如 Leaflet、OpenLayers、Mapbox）或处理空间数据时，大模型自身通常没有收录全球公开的地图服务地址，容易产生“幻觉”并生成错误链接。如果直接把几十万字的数据文件塞入 Prompt，不仅极其昂贵而且每次响应变慢。

GeoSource MCP 将整理好的本地 SQLite 数据库接入 MCP 接口，AI 在需要寻找数据源时，可以通过结构化接口直接查询真实的可用服务（覆盖 OGC WMS、WFS、WMTS、XYZ 瓦片、ArcGIS REST、STAC 等）。

### 核心优势与技术指标
- **0.05 秒级响应**：本地 SQLite 倒排与联合索引，毫秒级即刻返回检索结果。
- **节省 99% 以上 Token**：每次交互仅提取最相关的 3~5 条记录（约 200~500 Tokens），杜绝大文件塞入 Prompt 的高额开销。
- **杜绝接口幻觉**：返回的端点 URL、图层名、免 Key 属性均经过真实验证，保证代码中的图层可直接加载。
- **双向数据同步**：支持 Excel 表格与 SQLite 双向同步，并提供接口允许 AI 在使用中自动更新失效链接。

### 包含的数据内容
- **2,198+ 项主服务记录**：涵盖各国测绘机构、开放政府数据、高程/地形 DEM、卫星影像、交通、气象与环境数据等。
- **1,561+ 个子图层**：记录具体服务下属的图层名称，方便直接配置进代码。
- **50 余项属性字段**：服务协议、所属国家、数据格式、是否免费、是否需 Key、商业使用许可等。

### 提供的工具列表

| 工具名称 | 输入参数 | 功能说明 |
| :--- | :--- | :--- |
| `search_gis_services` | `keyword`（关键词）, `country`（国家）, `protocol`（协议）, `category`（分类）, `is_free`（是否免费）, `need_no_key`（是否免Key）, `limit` | 多条件筛选查询符合要求的空间服务。 |
| `get_service_detail` | `service_id`（服务ID，如 WMS-0001） | 获取该服务的完整信息及下属所有子图层名称。 |
| `list_categories_and_stats` | 无 | 查看数据库中服务分类、协议类型及国家分布统计。 |
| `query_gis_sql` | `query`（只读 SQL 语句） | 对 SQLite 数据库执行自定义只读 SQL 查询。 |
| `update_service_status` | `service_id`, `new_url`, `status`, `notes` | 修改某项服务的可用状态、更新新网址或追加备注。 |

### 使用方式

#### 1. 安装依赖
```bash
git clone https://github.com/Wukeeeeee/GeoSource-MCP.git
cd GeoSource-MCP
pip install mcp
```

#### 2. 本地测试
运行测试指令，确认数据库可正常检索：
```bash
python server.py --test
```

#### 3. 配置客户端连接

##### Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
  "mcpServers": {
    "geosource": {
      "command": "python",
      "args": ["E:/my_repo/GeoSource/server.py"]
    }
  }
}
```

##### Cursor / 其他 IDE
在 MCP 配置页面添加：
- **Command**: `python`
- **Args**: `E:/my_repo/GeoSource/server.py`

---

## 📄 开源协议 (License)
本项目采用 [MIT License](LICENSE)。