locan-tools

locan (CLI) and locan-mcp (MCP server) — local SEO tools for Google Business Profiles, on top of the Locan API.

Both are thin HTTP clients: no Google Places or LLM keys live on your machine. Point them at the hosted API or at your own self-hosted Locan instance.

Install

uvx --from locan-tools locan find-business "dentist kaunas"   # run without installing
pipx install locan-tools                               # isolated install
pip install locan-tools                                # into the current environment

Requires Python 3.11 or newer.

Commands

locan find-business "dentist kaunas"
locan gbp-audit --business-name "Smile Dental" --city Kaunas
locan gbp-categories --place-id PLACE_ID --keyword "dentist kaunas" --keyword "teeth whitening"
locan rank-grid --place-id PLACE_ID --keyword "dentist" --grid-size 5 --spacing-km 1
locan ai-visibility --business-name "Smile Dental" --city Kaunas --category dentist
locan review-reply --business-name "Smile Dental" --review-text "Friendly staff, no waiting." --rating 5
locan review-link PLACE_ID
locan schema-jsonld PLACE_ID

Every command prints JSON to stdout. Add --pretty before the command name for a compact table instead:

locan --pretty find-business "dentist kaunas"

API errors are printed to stderr as error: <message> (<code>) and exit with status 1.

Self-hosting

LOCAN_API_URL selects the API. It defaults to https://api.locan.ai/api; point it at your own instance to skip the hosted limits:

export LOCAN_API_URL=http://localhost:8080/api
locan find-business "dentist kaunas"

MCP server

locan-mcp exposes the same eight tools (find_business, gbp_audit, gbp_categories, rank_grid, ai_visibility, review_reply, review_link, schema_jsonld) to MCP clients over stdio.

Claude Code:

claude mcp add locan -- uvx --from locan-tools locan-mcp

Claude Desktop / Cursor:

{
  "mcpServers": {
    "locan": {
      "command": "uvx",
      "args": ["--from", "locan-tools", "locan-mcp"],
      "env": { "LOCAN_API_URL": "https://api.locan.ai/api" }
    }
  }
}

Streamable HTTP instead of stdio:

locan-mcp --http --port 8765

Cost and limits

The tools call Google Places and AI models through the Locan API, so they are not free to run. rank-grid is the most expensive: one Places request per grid cell, 25 for a 5×5 grid. Daily limits apply on the hosted API; self-host for unlimited runs.

License

AGPL-3.0-only. The full text is in LICENSE next to pyproject.toml (and at the repository root of the public repo).