Chuk MCP Map

楚科奇MCP地图

交互式地理空间可视化MCP服务器 --用于渲染地图、GeoJSON层、边界框和地形覆盖的通用模型上下文协议（MCP）服务器。

这是一个为学习和测试目的而提供的演示项目。

  

特性

此MCP服务器提供4个工具，用于从GeoJSON数据、图像叠加和图块层创建交互式地图视图。

所有工具都返回完全类型化的Pydantic v2模型 (MapContent / LayersContent)用于类型安全和验证。

智能自动弹出窗口：当特征具有属性（例如名称、温度、描述）时，会自动生成可点击的弹出窗口——不需要明确的弹出配置。内部钥匙(_id, fid, objectid等）被过滤掉，字段按优先级排序（名称、描述、类型优先），当名称和类型/类别都存在时，会生成“伦敦-纪念碑”等复合标题。

图层类型

工具

安装

使用紫外线（推荐）

# Install from PyPI
uv pip install chuk-mcp-map

# Or clone and install from source
git clone https://github.com/chrishayuk/chuk-mcp-map.git
cd chuk-mcp-map
uv sync --dev

使用pip

pip install chuk-mcp-map

用法

使用克劳德桌面

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "map": {
      "command": "uvx",
      "args": ["chuk-mcp-map"]
    }
  }
}

或者，如果在本地安装：

{
  "mcpServers": {
    "map": {
      "command": "chuk-mcp-map"
    }
  }
}

独立

# STDIO mode (default, for MCP clients)
uv run chuk-mcp-map

# HTTP mode (for web access)
uv run chuk-mcp-map http

查询示例

配置后，您可以向Claude提出以下问题：

• “给我看一张世界十大首都的地图”
• “在地图上标出这些地震位置”
• “在地图上突出显示英国的边界框”
• “在地图上显示此API响应的GeoJSON”
• “用缩略图覆盖这些卫星足迹”

工具参考

1. show_map --丰富的交互式地图

当您需要可点击的弹出窗口、样式标记、聚类、多层或图像/图块覆盖时，这是最好的工具。将数据放入GeoJSON功能属性中，弹出窗口将自动生成（或提供显式的弹出模板进行控制）。

参数：

图层定义（GeoJSON）：

{
  "id": "cities",
  "label": "UK Weather",
  "features": {
    "type": "FeatureCollection",
    "features": [{
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-0.12, 51.5] },
      "properties": { "name": "London", "temp": "12°C", "conditions": "Overcast", "wind": "18 km/h" }
    }]
  },
  "style": { "fillColor": "#3388ff", "fillOpacity": 0.4, "color": "#0044cc", "weight": 2 },
  "cluster": true
}

弹出窗口为 自动生成 从特征属性中——单击标记显示名称、温度、条件和风。要自定义，请添加显式 popup 字段： {"title": "{name}", "fields": ["temp", "conditions"]}.

图层定义（图像叠加）：

{
  "id": "thumbnail",
  "label": "Satellite Thumbnail",
  "layer_type": "image",
  "image_url": "https://example.com/thumb.jpg",
  "image_bounds": [[south_lat, west_lon], [north_lat, east_lon]],
  "opacity": 0.9,
  "visible": false
}

图层定义（平铺图层）：

{
  "id": "topo",
  "label": "USGS Topo",
  "layer_type": "tiles",
  "tile_url": "https://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/tile/{z}/{y}/{x}",
  "tile_attribution": "USGS The National Map",
  "tile_min_zoom": 0,
  "tile_max_zoom": 16
}

2. show_geojson --快速单层地图

获取地图的最快方法是传递原始GeoJSON，一切都是自动配置的。自动根据功能属性生成可点击的弹出窗口。使用 show_map 用于完全控制样式、集群和弹出模板。

参数：

3. show_bbox --边界框图

将边界框显示为高亮显示的多边形。可用于显示搜索范围或光栅覆盖范围。

参数：

4. show_layers --轻量级多层

简化的多层概览，无需每层样式或弹出窗口。使用 show_map 当你需要造型和交互性时。

参数：

建筑

src/chuk_mcp_map/
    __init__.py        # Package version
    server.py          # MCP server, 4 tool handlers, CLI entry point
    helpers.py         # GeoJSON parsing, bbox, centre/zoom, layer builders

建在上面 chuk mcp服务器 从观点 chuk视图模式:

• 装饰器: @map_tool 和 @layers_tool 从 chuk_view_schemas.chuk_mcp
• 返回类型: MapContent 和 LayersContent （Pydantic v2型号）
• 运输：STDIO（MCP客户端的默认设置）或HTTP(--http 旗帜）
• 无地理依赖性：纯Python GeoJSON处理——无GDAL、shapley或rasterio

发展

设置

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

# Install with uv (recommended)
uv sync --dev

# Or with pip
pip install -e ".[dev]"

运行测试

make test              # Run 158 tests
make test-cov          # Run tests with coverage
make coverage-report   # Show coverage report

代码质量

make lint      # Run linters
make format    # Auto-format code
make typecheck # Run type checking
make security  # Run security checks
make check     # Run all checks (lint, typecheck, security, test)

建筑

make build         # Build package
make docker-build  # Build Docker image
make docker-run    # Run Docker container

贡献

欢迎投稿！请随时提交拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

Apache许可证2.0——请参阅 许可证 了解详情。

致谢

• 传单 用于地图渲染引擎
• 模型上下文协议 对于MCP规范
• 人类 为Claude和MCP提供支持