@showmeonmap/mcp

Model Context Protocol server for ShowMeOnMap. Lets any MCP-speaking agent — Claude Desktop, Cursor, Zed, Windsurf, ChatGPT Apps SDK, custom LangGraph / CrewAI / Autogen agents — build and mutate geospatial maps over a typed tool surface.

Spec: docs/superpowers/specs/2026-04-17-mcp-server-design.md (in the parent repo).

Install

npx -y @showmeonmap/mcp

That's it. Or pin a version: npx -y @showmeonmap/[email protected].

The server speaks standard MCP/stdio; it's a thin proxy to the ShowMeOnMap HTTP API. Point it at production with your API key (below), or at a local checkout (default: http://localhost:3000).

Get an API key (production)

1. Sign in at showmeonmap.com and buy a credit pack (/pricing).
2. Account menu → API keys → Create key. Copy the smo_live_… key — it's shown once.
3. Every map your agent builds spends your credits at the same rates as the web app (1 credit per standard map or mutation, 3 per agent-grade map; reads are free). Refunds are automatic on failures.

Prefer no local process? Use the hosted remote endpoint directly — no install:

{
  "mcpServers": {
    "showmeonmap": {
      "url": "https://showmeonmap.com/api/mcp",
      "headers": { "Authorization": "Bearer smo_live_…" }
    }
  }
}

The hosted endpoint speaks streamable HTTP (stateless), is rate-limited to 30 requests/min per key, and works anywhere remote MCP servers do — Claude custom connectors, the OpenAI Responses API (server_url), Gemini managed agents (mcp_server), Cursor, Copilot Studio, Bedrock.

Wire into Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "showmeonmap": {
      "command": "npx",
      "args": ["-y", "@showmeonmap/mcp"],
      "env": {
        "SHOWMEONMAP_BASE_URL": "https://showmeonmap.com",
        "SHOWMEONMAP_API_KEY": "smo_live_…"
      }
    }
  }
}

Restart Claude Desktop. showmeonmap appears in the tools picker.

Cursor (~/.cursor/mcp.json), Zed, Windsurf, and any other MCP host follow the same shape — command: "npx", args: ["-y", "@showmeonmap/mcp"], plus the SHOWMEONMAP_BASE_URL + SHOWMEONMAP_API_KEY env. For local dev against a checkout, drop the key and set SHOWMEONMAP_BASE_URL=http://localhost:3000.

Run a ShowMeOnMap backend locally

The package is a client; you also need a backend. From a checkout of the main repo:

SMO_DISABLE_AUTH=1 SMO_DISABLE_CREDIT_GATE=1 SMO_DISABLE_RATE_LIMIT=1 npm run dev

(In production, point SHOWMEONMAP_BASE_URL at the hosted backend instead.)

Try it

Ask Claude Desktop things like:

• "Build me a map of volcanoes in Japan" → invokes build_map, returns a map_id + structured response
• "Now filter to ones above 2000m elevation" → invokes mutate_map, applies a filterLayer op
• "Change the basemap to satellite" → another mutate_map with setBasemap
• "Show me recent earthquakes" (unrelated) → outOfScope triggers; Claude can fall back to build_map
• "Remove it" (with a multi-layer map) → clarification with candidates

Tool surface (24 tools)

V1 — natural-language tools (3): build_map, mutate_map, get_state. V2 — direct-op tools (18): add_layer, filter_layer, clear_filters, remove_layer, rename_layer, restyle_layer, set_camera, set_time, set_basemap, select_within, subset_to_selection, query_features, add_annotation, remove_annotation, tag, undo, redo, report_blocker.

Every tool returns a three-channel envelope:

{
  "ok": true,
  "map_id": "…",
  "version": 5,
  "structured": { "workspace": {…}, "mapPlan": {…} },
  "shareable_url": "http://localhost:3000/m/…",
  "metadata": { "title": "…", "layer_count": 2, "last_updated": "…" },
  "next_actions": [
    { "label": "Filter to features where name is not empty", "argsTemplate": { "instruction": "…" } }
  ],
  "outOfScope": { "reason": "…" },
  "clarification": { "question": "…", "candidates": [ … ] }
}

The calling agent reasons over structured, surfaces shareable_url to its end user for interactive drill-down, and uses next_actions as typed hints for follow-up tool calls.

For the full Op catalog and predicate grammar that the V2 tools accept, fetch the MCP resource at showmeonmap://docs/workspace-ops-spec — agents should not guess these shapes.

Environment variables

| Var | Default | Purpose | |---|---|---| | SHOWMEONMAP_BASE_URL | http://localhost:3000 | Where the ShowMeOnMap HTTP API lives | | SHOWMEONMAP_API_KEY | (unset) | Your personal smo_live_… key — identifies you and spends your credits. Required against production; optional for a local dev checkout running with auth bypasses | | MCP_BLOCKER_LOG_PATH | reports/agent-blockers/<today>.ndjson (in the backend's cwd) | Where report_blocker tool calls are appended | | MCP_RATIONALE_LOG_PATH | reports/mcp-rationale/<today>.ndjson | Where typed-op rationales are persisted |

Run from a checkout (debugging)

If you have the main repo cloned and want to run the unbuilt source:

npm --prefix packages/mcp-server install
npm --prefix packages/mcp-server run build
node packages/mcp-server/dist/index.js

The integration test (requires backend on localhost:3000):

npx tsx packages/mcp-server/__tests__/stdio-roundtrip.test.ts

Spawns a fresh server process, exercises initialize → tools/list → every tool over NDJSON-framed JSON-RPC, asserts envelope shape. Exits 0 with a "skipping" notice if the backend isn't reachable.

Current limitations

• In-memory session cache. map_id → workspace mapping lives in the server process; restarts lose state. Phase I-3 (in the parent repo's plan) wires D1 persistence so shareable_url actually resolves across sessions.
• No preview PNG. The envelope's shareable_url points at the app's /m/<id> viewer, but workspaces aren't yet persisted in the gallery. Until I-3, share the raw structured response.
• stdio bin + hosted remote endpoint. This package's bin is stdio; remote hosts use https://showmeonmap.com/api/mcp (streamable HTTP, stateless). The standalone Node HTTP entry (packages/mcp-server/src/http.ts) remains for self-hosting a checkout.
• Auth is per-user API keys (smo_live_…, minted at showmeonmap.com). The key travels as a bearer on every backend call and bills the key's owner.

References

• Protocol: modelcontextprotocol.io
• SDK: @modelcontextprotocol/sdk
• Repo: github.com/FrankAIUser/showmeonmap