mcp-geo-tools by Epawse - MCP Server

MCP Geo Tools

A standard Model Context Protocol (MCP) server providing geographic spatial tools for 3D globe visualization.

Works with Claude Desktop, Claude Code, and any MCP-compatible client.

Features

Navigation: Fly to coordinates or known locations worldwide
Map Styles: Switch between satellite, vector, terrain, and dark basemaps
Markers: Add and manage point markers with labels
Weather Effects: Rain, snow, fog visual effects
Time Control: Day, night, dawn, dusk lighting

Quick Start

Using uvx (Recommended)

uvx mcp-geo-tools

Using pip

pip install mcp-geo-tools
mcp-geo-tools

Claude Desktop Integration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "geo-tools": {
      "command": "uvx",
      "args": ["mcp-geo-tools"]
    }
  }
}

Or if installed via pip:

{
  "mcpServers": {
    "geo-tools": {
      "command": "mcp-geo-tools"
    }
  }
}

Available Tools

Navigation

Tool	Description
`fly_to`	Fly to specific coordinates (longitude, latitude, altitude)
`fly_to_location`	Fly to a known location by name (e.g., "北京", "Paris")
`reset_view`	Reset camera to default view
`get_camera_position`	Get current camera position

Map Style

Tool	Description
`switch_basemap`	Switch basemap type: satellite, vector, terrain, dark
`switch_basemap_by_name`	Switch basemap using natural language

Markers

Tool	Description
`add_marker`	Add a marker at coordinates
`add_marker_at_location`	Add a marker at a known location
`remove_marker`	Remove a specific marker
`clear_markers`	Remove all markers

Weather

Tool	Description
`set_weather`	Set weather effect: rain, snow, fog, clear
`set_weather_by_name`	Set weather using natural language
`clear_weather`	Clear all weather effects

Time

Tool	Description
`set_time`	Set time preset: day, night, dawn, dusk
`set_time_by_name`	Set time using natural language

Available Resources

Resource URI	Description
`geo://locations`	All known locations with coordinates
`geo://locations/list`	List of location names
`geo://locations/china`	Locations in China
`geo://locations/world`	Locations outside China
`geo://basemaps`	Available basemap types
`geo://weather`	Available weather effects
`geo://time-presets`	Available time presets

Known Locations

The server includes 50+ pre-defined locations:

China: 北京, 上海, 广州, 深圳, 杭州, 成都, 故宫, 长城, 西湖, 外滩...

World: New York, Paris, London, Tokyo, Sydney, Eiffel Tower, Statue of Liberty, Pyramids...

Execution Modes

This MCP server supports two execution modes:

Instruction Mode (Default)

Returns JSON action commands that can be executed by a compatible client:

{
  "mode": "instruction",
  "action": "fly_to",
  "arguments": {"longitude": 116.4074, "latitude": 39.9042, "altitude": 5000},
  "message": "飞往坐标 (116.4074, 39.9042)"
}

Execute Mode

When GeoCommander is running, actions are executed directly via HTTP API:

# Enable execute mode
export GEOCOMMANDER_URL=http://localhost:8765
export MCP_GEO_MODE=execute  # or "auto" for automatic detection

mcp-geo-tools

In execute mode, the MCP server:

Sends action commands to GeoCommander's /execute endpoint
GeoCommander broadcasts to connected Cesium frontend
Returns execution result to the LLM

Configuration

Environment Variable	Description	Default
`GEOCOMMANDER_URL`	GeoCommander HTTP API URL	`http://localhost:8765`
`MCP_GEO_MODE`	Execution mode: `instruction`, `execute`, or `auto`	`auto`

Claude Desktop with Execute Mode

{
  "mcpServers": {
    "geo-tools": {
      "command": "uvx",
      "args": ["mcp-geo-tools[execute]"],
      "env": {
        "GEOCOMMANDER_URL": "http://localhost:8765",
        "MCP_GEO_MODE": "auto"
      }
    }
  }
}

HTTP Transport Mode

For web applications, run in HTTP mode:

mcp-geo-tools --http --port 8766

This starts a Streamable HTTP server that web clients can connect to.

Usage Examples

In Claude Desktop or any MCP client:

"带我去故宫看看" → Flies to the Forbidden City
"切换到卫星地图" → Switches to satellite basemap
"下雪效果" → Adds snow weather effect
"设置成黄昏" → Sets time to dusk
"在西湖添加标记" → Adds a marker at West Lake

Development

Setup

git clone https://github.com/Epawse/mcp-geo-tools.git
cd mcp-geo-tools
pip install -e ".[dev]"

Run Tests

pytest

Project Structure

mcp-geo-tools/
├── src/mcp_geo_tools/
│   ├── __init__.py
│   ├── server.py           # MCP server entry point
│   ├── tools/
│   │   ├── navigation.py   # Camera/flight tools
│   │   ├── basemap.py      # Map style tools
│   │   ├── markers.py      # Marker management
│   │   ├── weather.py      # Weather effects
│   │   └── time.py         # Time/lighting
│   ├── resources/
│   │   └── locations.py    # Location database
│   └── prompts/
│       └── templates.py    # System prompts
├── tests/
├── pyproject.toml
└── README.md

Integration with GeoCommander

This MCP server is designed to work with GeoCommander, a 3D globe visualization application built with Cesium.js.

Architecture

┌─────────────────┐     MCP Protocol     ┌─────────────────┐
│  Claude Desktop │◄───────────────────► │  mcp-geo-tools  │
│  / Claude Code  │                      │   (MCP Server)  │
└─────────────────┘                      └────────┬────────┘
                                                  │
                                         HTTP POST /execute
                                                  │
                                                  ▼
                                         ┌─────────────────┐
                                         │  GeoCommander   │
                                         │ (FastAPI Server)│
                                         └────────┬────────┘
                                                  │
                                            WebSocket
                                                  │
                                                  ▼
                                         ┌─────────────────┐
                                         │  Cesium Viewer  │
                                         │   (Frontend)    │
                                         └─────────────────┘

How It Works

User talks to Claude (via Claude Desktop or Claude Code)
Claude calls MCP tools (e.g., fly_to("北京"))
MCP Server sends action to GeoCommander via HTTP
GeoCommander broadcasts to connected Cesium frontend via WebSocket
Cesium viewer executes the action (camera flies to Beijing)

Running the Full Stack

# Terminal 1: Start GeoCommander backend
cd geocommander/mcp-server
python server.py

# Terminal 2: Start Cesium frontend
cd geocommander/web
npm run dev

# Terminal 3: Use with Claude Desktop or Claude Code
# (Configure as shown in "Claude Desktop with Execute Mode" section)

License

MIT License - see file.