MBTileServer

Vector maps with GL styles. Lightweight map tile server for MapLibre GL JS, Leaflet, OpenLayers, GIS via WMTS, etc.

Note: This is a light-weight fork of TileServer GL, focused on serving vector tiles (MBTiles/PMTiles) without server-side raster rendering.

Features

• MBTiles support — Serve vector tiles from local SQLite databases
• PMTiles support — Cloud-optimized tile archives with HTTP range requests
• Zero native dependencies — Pure JavaScript, runs on Windows, macOS, and Linux
• Built-in preview — Interactive map viewer powered by MapLibre GL JS 5.x
• Rich viewer UI — Layer list, search, drag-and-drop reorder, visibility toggle, inline rename, duplicate, style editor with color picker
• Style editor — Edit layer paint/layout properties via JSON, with cascading preset dropdowns (fill/line/circle/symbol)
• Color picker — Double-click color swatches to modify colors with native color input
• Map pick & popup — Click on map to query rendered features and navigate to layers
• Style upload/download — Import/export MapLibre style.json on the fly
• TileJSON / WMTS — Standard OGC-compatible service endpoints
• Static files — Serve custom fonts, sprites, images via /files/
• Lightweight — No Canvas, no MapLibre GL Native, no heavy raster rendering pipeline

Requirements

• Node.js v20+ (v22 LTS recommended)
• npm

node --version  # v22.x.x
npm --version   # 10.x.x

Install

From source (local)

git clone https://gitee.com/mapbox-gl/mbtileserver.git
cd mbtileserver
npm install -g .

Verify installation

mbtileserver --version
# 5.6.3

Quick Start

Serve a single MBTiles file

mbtileserver zurich_switzerland.mbtiles -p 8080

Then open http://localhost:8080 in your browser.

Serve with a config file

Create config.json:

{
  "options": {
    "port": 8080,
    "cors": true,
    "serveStatic": true,
    "serveStyles": true,
    "servePreview": true,
    "paths": {
      "root": "",
      "fonts": "fonts",
      "styles": "styles",
      "files": "public/files"
    }
  },
  "data": {
    "zurich": {
      "mbtiles": "zurich_switzerland.mbtiles"
    }
  },
  "styles": {}
}

Start the server:

mbtileserver -c config.json -p 8080

Development

Run in development mode with hot-reload (via nodemon):

npm run dev

This watches src/ and public/ for changes and auto-restarts the server.

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --file <file> | MBTiles or PMTiles file | — | | -c, --config <file> | Configuration file | config.json | | -p, --port <port> | Server port | 8080 | | -b, --bind <address> | Bind address | 0.0.0.0 | | -u, --public_url <url> | Public URL (for reverse proxy) | — | | -C, --no-cors | Disable CORS headers | — | | --ignore-missing-files | Skip missing data sources on startup | — | | -V, --verbose [level] | Verbose logging (1-3) | — | | -s, --silent | Less output | — | | -v, --version | Show version | — | | -h, --help | Show help | — |

API Endpoints

| Endpoint | Description | |----------|-------------| | / | Home page with map preview | | /data | List all data sources | | /data/{id}.json | TileJSON metadata | | /data/{id}/{z}/{x}/{y}.pbf | Vector tiles | | /files/{path} | Static files (fonts, sprites, images) | | /styles/{id}.json | GL style JSON |

Viewer Features

The built-in MapLibre viewer (/data/{id}) provides a rich layer management UI:

• Layer list — Right-side panel showing all layers with type icons (fill/line/circle/symbol)
• Search & filter — Quick filter layers by name
• Visibility toggle — Checkbox to show/hide individual layers
• Drag & drop reorder — Drag layers to change draw order
• Inline rename — Double-click layer name to edit its ID
• Duplicate — Click + to clone a layer with identical style
• Style editor — Click layer color box to open modal with:
  • Live JSON editor with syntax highlighting
  • Cascading preset dropdowns (type + category) for quick style defaults
  • Color swatch extraction — double-click to pick colors
  • Native color picker integration
• Layer order modal — Top-left button to reorder source-layers via textarea
• Style upload/download — Import/export full MapLibre style.json
• Map click picking — Click on map to query features and jump to layers

Data Sources

MBTiles

Standard SQLite-based tile archive. Download sample data from OpenMapTiles or generate your own.

mbtileserver data.mbtiles

PMTiles

Cloud-optimized format supporting remote HTTP(S) sources:

mbtileserver https://example.com/data.pmtiles

Static Files

Place custom fonts, sprites, images, or any static assets in public/files/ (or configure via options.paths.files). They become accessible at:

http://localhost:8080/files/sprite.png
http://localhost:8080/files/custom-font/{range}.pbf

In your style.json, reference local files with the local://files/ protocol:

{
  "sprite": "local://files/sprite",
  "glyphs": "local://fonts/{fontstack}/{range}.pbf"
}

Security: Host Header Poisoning Mitigation

When started without --public_url, response URLs are built from request headers (Host, X-Forwarded-*). For production deployments, either:

1. Set a public URL:

   mbtileserver --public_url https://tiles.example.com/ --file data.mbtiles

2. Restrict allowed hosts:

   export TILESERVER_GL_ALLOWED_HOSTS="localhost,tiles.example.com"
   mbtileserver --file data.mbtiles

License

BSD-2-Clause. See LICENSE.md.

Copyright (c) 2023 MapTiler.com, 2016 Klokan Technologies GmbH.