OpenMapTiles MCP Server

A Model Context Protocol (MCP) server for efficient coastline data extraction from OpenMapTiles-compatible vector tile services.

Features

• 🌊 Extract coastlines from water polygon boundaries
• 🚀 Parallel tile fetching for better performance
• 💾 Smart caching to reduce API calls
• 🔄 Automatic provider fallback
• 📏 Zoom-based simplification
• 🏝️ Island coastline detection

Installation

From Repository

# Clone the repository
git clone https://github.com/your-username/openmaptiles-mcp.git
cd openmaptiles-mcp

# Install dependencies
npm install

# Build the project
npm run build

Installing in Claude Desktop

1. Build from source (if not already done):

   npm install
   npm run build

2. Add to Claude Desktop configuration:

   Edit your Claude Desktop configuration file:

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

   Add the server to your MCP servers list:

   {
     "mcpServers": {
       "openmaptiles": {
         "command": "node",
         "args": ["/absolute/path/to/openmaptiles-mcp/dist/index.js"],
         "env": {
           "MAPTILER_API_KEY": "your-optional-api-key"
         }
       }
     }
   }

   Replace /absolute/path/to/openmaptiles-mcp with the actual path to your cloned repository.

3. Restart Claude Desktop to load the new MCP server.

Installing in Claude Code

Add the server using the Claude Code CLI:

# Add to current project
claude mcp add openmaptiles --scope project -- node /path/to/openmaptiles-mcp/dist/index.js

# Add globally for all projects
claude mcp add openmaptiles --scope user -- node /path/to/openmaptiles-mcp/dist/index.js

# With environment variables
claude mcp add openmaptiles -e MAPTILER_API_KEY=your_key --scope project -- node /path/to/openmaptiles-mcp/dist/index.js

# Using npx (if published to npm)
claude mcp add openmaptiles --scope project -- npx openmaptiles-mcp

# Verify installation
claude mcp list

Usage

As an MCP Server

npm start

Development

npm run dev

MCP Tools

get_coastline_by_bounds

Retrieve coastline vectors within a geographic bounding box.

{
  "bounds": {
    "minLat": 37.7,
    "maxLat": 37.8,
    "minLon": -122.5,
    "maxLon": -122.4
  },
  "zoom": 12,
  "simplify": true,
  "includeIslands": true,
  "page": 1,
  "limit": 50
}

get_water_features

Fetch raw water polygon features from vector tiles.

{
  "bounds": {
    "minLat": 37.7,
    "maxLat": 37.8,
    "minLon": -122.5,
    "maxLon": -122.4,
    "zoom": 12
  },
  "page": 1,
  "limit": 50
}

extract_coastline_from_water

Convert water polygon features to coastline LineStrings.

{
  "waterFeatures": [...],
  "includeIslands": true
}

get_tile_info

Calculate tile coordinates and coverage for a given location.

{
  "lat": 37.7749,
  "lon": -122.4194,
  "zoom": 12
}

simplify_coastline

Apply Douglas-Peucker simplification to coastline features.

{
  "features": {...},
  "zoom": 12
}

Environment Variables

• MAPTILER_API_KEY - Optional API key for MapTiler fallback provider
• MAX_MEMORY_CACHE - Maximum memory cache size in MB (default: 100)
• REQUEST_TIMEOUT - Tile request timeout in milliseconds (default: 5000)

Development

# Run tests
npm test

# Run linting
npm run lint

# Type checking
npm run typecheck

# Format code
npm run format

Testing

# Unit tests
npm run test:unit

# E2E tests
npm run test:e2e

# All tests with coverage
npm run test:all

Data Providers

1. OpenFreeMap (Primary) - No authentication required
2. Versatiles (Secondary) - No authentication required
3. MapTiler (Fallback) - Requires API key

License

MIT

Contributing

See CLAUDE.md for development guidelines and PROJECT.md for detailed specifications.