topo-shadow-box

topo-shadow-box

An MCP (Model Context Protocol) server that generates 3D-printable topographic shadow boxes. Given a geographic area, it fetches real elevation data and OpenStreetMap features, then produces multi-material 3MF files ready for slicing and printing.

Features

• Terrain mesh from AWS Terrain-RGB elevation tiles (free, global coverage)
• OpenStreetMap overlay: roads, water bodies, and buildings
• GPX track visualization as raised strips on the terrain
• Multiple output shapes: square, circle, hexagon, rectangle
• Export to 3MF (multi-material), OpenSCAD .scad, or SVG map insert
• Live 3D preview via a local Three.js viewer (port 3333)
• Session save/load to resume work across server restarts

Installation

Download a prebuilt binary from GitHub Releases, or build from source with Go:

cd go
go build -o /usr/local/bin/topo-shadow-box ./cmd/topo-shadow-box

Adding to Claude Code

/plugin marketplace add huslage/topo-shadow-box
/plugin install topo-shadow-box@topo-shadow-box

The MCP server starts automatically when you install the plugin.

Adding to Codex

Add this to ~/.codex/config.toml:

[mcp_servers.topo-shadow-box]
command = "topo-shadow-box"
args = ["serve"]

Then restart Codex.

Permissions

The first time Claude calls each tool, it will ask for permission. Click "Allow always" (not "Allow") so the approval is saved and you won't be asked again.

If you'd rather pre-approve everything upfront, add this to your ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__plugin_topo-shadow-box_topo-shadow-box__*"]
  }
}

CLI Usage

The Go binary supports two modes:

• topo-shadow-box serve starts the MCP server (Claude Code plugin mode).
• topo-shadow-box [flags] runs one-shot CLI generation and writes an output file.

Build the Binary

cd go
go build -o /usr/local/bin/topo-shadow-box ./cmd/topo-shadow-box

Quickstart Examples

# Circle area -> 3MF
topo-shadow-box --lat 35.99 --lon -78.90 --radius 5000 --output durham.3mf

# Bounding box -> OpenSCAD
topo-shadow-box --north 36.1 --south 35.9 --east -78.8 --west -79.0 --output area.scad

# GPX track area -> SVG
topo-shadow-box --gpx /path/to/ride.gpx --output ride.svg

# Custom model options + subset of map features
topo-shadow-box \
  --lat 35.99 --lon -78.90 --radius 5000 \
  --output model.3mf \
  --width 150 \
  --vertical-scale 2.0 \
  --base-height 8 \
  --shape circle \
  --resolution 250 \
  --features roads,water \
  --color-terrain "#8B7355" \
  --color-water "#4A90D9"

CLI Flag Reference

Flag	Default	Description
--lat, --lon, --radius	—	Circular area input (radius in meters)
--north, --south, --east, --west	—	Explicit bounding box input
--gpx	—	GPX file path (uses GPX bounds + default padding)
--output, -o	—	Output path; extension selects format (.3mf, .scad, .svg)
--width	200	Model width in mm
--vertical-scale	1.5	Elevation exaggeration multiplier
--base-height	10	Solid base thickness in mm
--shape	square	square, circle, hexagon, rectangle
--resolution	200	Elevation grid resolution per axis
--features	roads,water,buildings	CSV feature list; use empty string to skip features
--color-terrain	#C8A882	Terrain color
--color-roads	#D4C5A9	Roads color
--color-water	#4682B4	Water color
--color-buildings	#E8D5B7	Buildings color
--color-gpx-track	#FF0000	GPX track color

Validation Rules

• Exactly one input mode is required:
  • --lat + --lon + --radius
  • --north + --south + --east + --west
  • --gpx
• --output is required.
• --shape must be one of square, circle, hexagon, rectangle.
• Colors must be #RRGGBB.
• Output format is inferred from file extension.

Run as MCP Server

topo-shadow-box serve

CLI Troubleshooting

• error: --output is required

  • Add --output <path> (or -o <path>). The extension must be .3mf, .scad, or .svg.

• one of --lat/--lon/--radius, --north/--south/--east/--west, or --gpx is required

  • Provide exactly one input mode. Do not mix coordinate/bbox/GPX inputs.

• --lat/--lon/--radius ... are mutually exclusive (or bbox/GPX equivalent)

  • Remove extra input flags so only one area-definition method is used.

• cannot infer output format from extension ...

  • Use a supported output extension: .3mf, .scad, or .svg.

• invalid --shape ...

  • Use one of: square, circle, hexagon, rectangle.

• Color format errors (must be in #RRGGBB format)

  • Use 6-digit hex with leading #, e.g. #C8A882.