@placeslayer/mcp

MCP server for PlacesLayer — geographic intelligence tools for AI agents.

Gives any MCP-compatible AI assistant (Claude Desktop, Cursor, n8n, etc.) access to PlacesLayer's proprietary dataset: fuzzy city resolution, AI-powered insights, vector similarity search, and more.

Why

LLMs already know country names and major capitals. This MCP is not for that.

It's useful when you need:

• Canonical IDs — normalize dirty/misspelled city names to your internal codes
• Proprietary AI insights — vibe, cost of living, climate zone, ideal_for tags (not in any LLM training data)
• Vector similarity — find cities similar in character to a reference city
• Criteria-based filtering — "low cost cities in Brazil with tropical climate, ideal for remote work"

Setup

You'll need a PlacesLayer API key. The free plan includes fuzzy_resolve and search_cities. Premium tools require a paid plan.

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

{
  "mcpServers": {
    "placeslayer": {
      "command": "npx",
      "args": ["-y", "@placeslayer/mcp"],
      "env": {
        "PLACESLAYER_API_KEY": "pk_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You'll see a 🔌 icon confirming the server connected.

Cursor

In .cursor/mcp.json at the project root (or globally in ~/.cursor/mcp.json):

{
  "mcpServers": {
    "placeslayer": {
      "command": "npx",
      "args": ["-y", "@placeslayer/mcp"],
      "env": {
        "PLACESLAYER_API_KEY": "pk_live_your_key_here"
      }
    }
  }
}

Any MCP client (remote HTTP mode)

If you're self-hosting the HTTP server (see below), point your client at the URL:

{
  "mcpServers": {
    "placeslayer": {
      "url": "https://mcp.yourserver.com/mcp",
      "headers": {
        "X-API-Key": "pk_live_your_key_here"
      }
    }
  }
}

Tools

fuzzy_resolve

Resolve messy city/province names to canonical IDs. Handles typos, abbreviations, and regional spellings.

Input:  ["bsas", "cba", "mza"]  (country: AR)
Output: Buenos Aires, Córdoba, Mendoza — each with city_code and confidence score

search_cities

Keyword search to find a city's code before passing it to other tools.

semantic_search ⭐ Premium

Natural language city search against PlacesLayer's vector embeddings.

"affordable coastal city good for remote workers" → ranked city list

city_insights ⭐ Premium

AI-generated structured data for a city: vibe, cost_of_living, climate_zone, ideal_for, summary.

similar_cities ⭐ Premium

Find cities with similar character to a reference city (pgvector cosine similarity).

"cities similar to Medellín" → comparable cities ranked by embedding distance

find_cities_by_criteria ⭐ Premium

Filter all cities in a country by structured insight attributes.

country: BR, cost_of_living: low, climate_zone: tropical, ideal_for: remote_work

compare_cities ⭐ Premium

Fetch insights for 2–8 cities in parallel and return a side-by-side comparison.

Self-hosting (HTTP mode)

Run the HTTP server if you want a remote endpoint instead of a local subprocess:

npm install -g @placeslayer/mcp
PORT=3000 PLACESLAYER_BASE_URL=https://api.placeslayer.com placeslayer-mcp-serve

Or with Docker:

FROM node:22-alpine
RUN npm install -g @placeslayer/mcp
ENV PLACESLAYER_BASE_URL=https://api.placeslayer.com
EXPOSE 3000
CMD ["placeslayer-mcp-serve"]

The server is stateless — each request authenticates via X-API-Key header forwarded to the PlacesLayer API. No database required.

Endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /mcp | MCP JSON-RPC — tool calls, initialize | | GET | /mcp | SSE stream for streaming clients | | GET | /health | Liveness check |

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PLACESLAYER_API_KEY | Yes (stdio mode) | — | Your PlacesLayer API key | | PLACESLAYER_BASE_URL | No | https://api.placeslayer.com | API base URL | | PORT | No (HTTP mode) | 3000 | HTTP server port |

License

MIT