caltopo-mcp

HTTP MCP server for managing CalTopo maps from headless agents.

This server is designed for a Hermes/Codex-style agent that needs to list maps, create folders, manage markers, and import/export GPX/KML without using a browser session.

Status

• Uses CalTopo private-account activation credentials.
• Does not require Chrome, Playwright, a desktop login, or a UI session.
• Runs as a normal headless Node.js process.
• Exposes a local HTTP MCP endpoint.
• Tested against a private CalTopo account for read/write marker and folder operations.

CalTopo does not publicly document this private-account API for general third-party use. Treat the integration as pragmatic and test bulk writes on disposable maps first.

Repository

Canonical repository:

https://github.com/sttts/caltopo-mcp

Do not commit local credentials. Runtime secrets belong in .data/, environment variables, or a local secret manager.

Features

• Account auth check
• Map listing
• Raw map data retrieval
• Folder list/create/update/delete
• Marker list/create/update/delete
• GPX waypoint import as CalTopo markers
• KML point placemark import as CalTopo markers
• GPX/KML marker export
• Optional Bearer token on the MCP endpoint
• macOS LaunchDaemon template for headless operation

Requirements

• Node.js 22 or newer
• npm
• A CalTopo account
• CalTopo activation credentials

On the Hermes Mac mini, the bundled Node runtime is expected at:

/Users/hermes/.hermes/node/bin/node

Credentials

The server supports two credential modes.

Activation File

Preferred for local operation:

CALTOPO_ACTIVATION_FILE=.data/activation.local.json

The activation file has this shape:

{
  "account": {
    "id": "..."
  },
  "code": "...",
  "key": "..."
}

Keep the file outside Git:

mkdir -p .data
chmod 700 .data
chmod 600 .data/activation.local.json

.data/ is ignored by Git.

Environment Variables

Alternative for service managers or secret stores:

CALTOPO_ACCOUNT_ID=...
CALTOPO_CREDENTIAL_ID=...
CALTOPO_CREDENTIAL_KEY=...

Never hardcode these values in source files, plist files, shell scripts, README examples, or committed config.

Getting Activation Credentials

Open an activation URL in a browser where you are logged in to CalTopo:

https://caltopo.com/app/activate/localhost/client/finish-activate?code=<CODE>&name=mcp

Then resolve the code locally:

CALTOPO_ACTIVATION_CODE=<CODE> python3 - <<'PY'
import os
import urllib.request

code = os.environ["CALTOPO_ACTIVATION_CODE"]
path = ".data/activation.local.json"
os.makedirs(".data", exist_ok=True)

with urllib.request.urlopen(f"https://caltopo.com/api/v1/activate?code={code}", timeout=20) as response:
    data = response.read()

fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(fd, "wb") as handle:
    handle.write(data)

print(f"wrote {path}")
PY

Local Development

npm install
npm run typecheck
npm run build
CALTOPO_ACTIVATION_FILE=.data/activation.local.json npm start

Default endpoint:

http://127.0.0.1:8788/mcp

Health check:

curl -sS http://127.0.0.1:8788/health

The health endpoint intentionally does not return credential values or account IDs.

Configuration

Environment variables:

CALTOPO_ACTIVATION_FILE=.data/activation.local.json
CALTOPO_ACCOUNT_ID=...
CALTOPO_CREDENTIAL_ID=...
CALTOPO_CREDENTIAL_KEY=...
CALTOPO_DOMAIN=caltopo.com
CALTOPO_MCP_HOST=127.0.0.1
CALTOPO_MCP_PORT=8788
CALTOPO_MCP_TOKEN=optional-bearer-token

CALTOPO_MCP_TOKEN protects the MCP endpoint with:

Authorization: Bearer <token>

Keep the server bound to 127.0.0.1 unless you also configure authentication and network-level access control.

MCP Tools

• caltopo_auth_status
• caltopo_list_maps
• caltopo_get_map
• caltopo_list_folders
• caltopo_create_folder
• caltopo_update_folder
• caltopo_delete_folder
• caltopo_list_markers
• caltopo_create_marker
• caltopo_update_marker
• caltopo_delete_marker
• caltopo_import_markers
• caltopo_export_markers

Example Tool Payloads

Create a marker:

{
  "map_id": "ABCDE12",
  "title": "Camp",
  "lat": 65.90993,
  "lon": -23.84598,
  "description": "Overnight stop",
  "color": "#00AAFF",
  "symbol": "point"
}

Import GPX waypoints:

{
  "map_id": "ABCDE12",
  "format": "gpx",
  "content": "<?xml version=\"1.0\"?><gpx><wpt lat=\"65.9\" lon=\"-23.8\"><name>Test</name></wpt></gpx>",
  "dry_run": true
}

Use dry_run: true before bulk imports.

Headless Service Scripts

Manual operation:

bin/start-caltopo-mcp.sh
bin/status-caltopo-mcp.sh
bin/stop-caltopo-mcp.sh

Do not use cron for this service. On macOS, use the LaunchDaemon in deploy/local.caltopo-mcp.plist if the server must survive reboots without an active UI login.

Hermes Deployment

Recommended layout on the Mac mini:

/Users/hermes/Quellen/caltopo-mcp
/Users/hermes/Quellen/caltopo-mcp/.data/activation.local.json

Clone and build:

cd /Users/hermes/Quellen
git clone https://github.com/sttts/caltopo-mcp.git caltopo-mcp
cd caltopo-mcp
PATH=/Users/hermes/.hermes/node/bin:$PATH npm install
PATH=/Users/hermes/.hermes/node/bin:$PATH npm run build

Start manually:

cd /Users/hermes/Quellen/caltopo-mcp
bin/start-caltopo-mcp.sh

Register with Hermes:

/Users/hermes/.local/bin/hermes mcp add caltopo --url http://127.0.0.1:8788/mcp
/Users/hermes/.local/bin/hermes mcp test caltopo

macOS LaunchDaemon

For reboot-safe headless operation, install the LaunchDaemon as root:

cd /Users/hermes/Quellen/caltopo-mcp
sudo bin/install-launchdaemon.sh

The plist runs the process as hermes:

/Library/LaunchDaemons/local.caltopo-mcp.plist

Check the service:

launchctl print system/local.caltopo-mcp
bin/status-caltopo-mcp.sh
/Users/hermes/.local/bin/hermes mcp test caltopo

Remove it:

sudo launchctl bootout system /Library/LaunchDaemons/local.caltopo-mcp.plist
sudo rm -f /Library/LaunchDaemons/local.caltopo-mcp.plist

Updating

cd /Users/hermes/Quellen/caltopo-mcp
git pull --ff-only
PATH=/Users/hermes/.hermes/node/bin:$PATH npm install
PATH=/Users/hermes/.hermes/node/bin:$PATH npm run build
bin/stop-caltopo-mcp.sh
bin/start-caltopo-mcp.sh

If the LaunchDaemon is installed:

sudo launchctl kickstart -k system/local.caltopo-mcp

Security Checklist

• .data/ is ignored by Git.
• Activation credentials are not present in source files.
• The health endpoint does not expose account IDs or credential metadata.
• The default bind address is 127.0.0.1.
• Use CALTOPO_MCP_TOKEN before exposing the endpoint beyond loopback.
• Prefer dry_run for imports before writing many markers.

Before publishing:

git status --short
git ls-files
rg -n "activation\\.local|CALTOPO_CREDENTIAL|credentialKey|Bearer|token|gmail|account_id" . \
  -g '!node_modules' -g '!dist' -g '!.data' -g '!.git'