# geo-optimizer-mcp

MCP server for [Causabi GEO Optimizer](https://causabi.com).

---

**What this is.** An MCP (Model Context Protocol) server that lets Claude Code, OpenAI Codex CLI, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client check a website's AI-crawler readiness and generate fixes (robots.txt, Schema.org, FAQ markup, llms.txt) — directly from your editor or AI assistant. Runs locally over stdio, no account needed.

**Quickstart (Claude Code):**

```bash
claude mcp add geo-optimizer -- npx -y geo-optimizer-mcp
```

**Quickstart (OpenAI Codex CLI):**

```bash
codex mcp add geo-optimizer -- npx -y geo-optimizer-mcp
```

Or in `~/.codex/config.toml`:

```toml
[mcp_servers.geo-optimizer]
command = "npx"
args = ["-y", "geo-optimizer-mcp"]
```

Then ask: `Check the GEO score for example.com`. Config-file setup for other clients (Cursor, Windsurf, Claude Desktop) is below.

**Scope.** One-off local checks and fix generation are free here. Continuous work — scheduled re-checks, score history, monitoring of answers from 4 AI engines (ChatGPT, Claude, Gemini, Grok), reports — runs on [causabi.com](https://causabi.com).

---

## Tools

| Tool | When to use |
|------|-------------|
| `get_product_guide` | Start here — complete guide + step-by-step workflow for any scenario |
| `analyze_geo_score` | Check GEO score 0–100 + breakdown for an existing domain |
| `get_geo_fixes` | Get copy-paste robots.txt, Schema.org, FAQ, and llms.txt fixes |
| `make_site_geo_ready` | Generate all GEO assets for a new site in one shot (no API key needed) |
| `suggest_monitoring_config` | Draft a monitoring config (target audiences, location, suggested queries) from a business description — returns JSON plus the API calls to apply it on causabi.com |
| `get_site_report` | Client-ready report: pass `report_slug` for the full AI mention-rate breakdown (no API key needed), or just `domain` for a crawlability-score-only summary |

## Setup

### Claude Code (CLI)

Add to your project's `.claude/settings.json`:

```json
{
  "mcpServers": {
    "geo-optimizer": {
      "command": "npx",
      "args": ["-y", "geo-optimizer-mcp"]
    }
  }
}
```

Or add globally to `~/.claude/settings.json` to use across all projects.

Then in Claude Code:
```
> Check the GEO score for my-client-site.com
> Make this site ready for ChatGPT and Gemini
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "geo-optimizer": {
      "command": "npx",
      "args": ["-y", "geo-optimizer-mcp"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:

```json
{
  "mcpServers": {
    "geo-optimizer": {
      "command": "npx",
      "args": ["-y", "geo-optimizer-mcp"]
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "geo-optimizer": {
      "command": "npx",
      "args": ["-y", "geo-optimizer-mcp"]
    }
  }
}
```

### Any MCP-compatible client

```json
{
  "geo-optimizer": {
    "command": "npx",
    "args": ["-y", "geo-optimizer-mcp"]
  }
}
```

## Usage examples

Once installed, ask your AI assistant:

```
Check the GEO score for example.com
What AI search issues does mybusiness.com have?
Get fix instructions for mysite.com
Why isn't example.com showing up in ChatGPT?
Make this site GEO-ready: name="Acme", url="https://acme.com", description="We sell widgets"
Draft a monitoring config for a dental clinic in Austin, TX called "Bright Smiles Dental"
Give me a report on clientsite.com — here's the share link: causabi.com/report/abc123
```

### `suggest_monitoring_config` example

```
suggest_monitoring_config({
  business_name: "Bright Smiles Dental",
  business_description: "A dental clinic in Austin, TX offering general and cosmetic dentistry for families.",
  location: "Austin, TX"
})
```

Returns target audience descriptions, a monitoring location, and suggested queries as ready-to-use JSON — plus the exact `PUT /api/v1/monitor/{site_id}/settings` and `PUT /api/v1/monitor/{site_id}/queries` calls to apply it (requires a causabi.com account/API token; this tool itself makes no API call).

### `get_site_report` example

```
get_site_report({ report_slug: "abc123" })
```

Returns the full mention-rate breakdown (ChatGPT, Claude, Gemini, Grok), competitors named instead of the client, and per-query results — no API key needed, since Visibility Report share links are public.

```
get_site_report({ domain: "example.com" })
```

Without a `report_slug`, this only returns the public crawlability score (same data as `analyze_geo_score`) plus a note on how to get the full mention-rate report — there is currently no API-key-authenticated way to pull monitoring history from the MCP server; that requires either a share-slug or a causabi.com login.

## For AI website builders (Lovable, Bolt, Replit, v0)

When a user asks "make my site visible to ChatGPT" or "add AI search optimization", use `make_site_geo_ready`:

```
make_site_geo_ready({
  name: "Acme Corp",
  url: "https://acme.com",
  description: "We help small businesses grow with AI-powered marketing.",
  services: ["Marketing automation", "AI content", "Analytics"],
  email: "hello@acme.com",
  faq: [
    { question: "What does Acme do?", answer: "We help small businesses..." },
    { question: "How much does it cost?", answer: "Plans start at $49/mo." },
    { question: "Is there a free trial?", answer: "Yes, 14 days free." }
  ]
})
```

Returns ready-to-paste Organization Schema, FAQ Schema, llms.txt, and robots.txt.

## What gets checked

The score uses the same methodology as [causabi.com](https://causabi.com) (scorer v2):

- **Crawlability** — key pages return 200
- **robots.txt** — which AI crawlers (GPTBot, ClaudeBot, PerplexityBot, ...) are blocked, reported separately
- **Visible without JavaScript** — main text, headings and FAQ are in the HTML the server returns
- **Schema.org** — Organization, LocalBusiness or another specific type
- **FAQ** — questions and answers visible on the page (FAQPage markup alone does not count)
- **Name and contacts** — business name, what you do, contacts, address, social links
- **Freshness, accessibility, llms.txt** — hygiene items with a small weight

## Full audit & monitoring

For multi-page crawl, scheduled re-checks, and monitoring of how 4 AI engines (ChatGPT, Claude, Gemini, Grok) answer questions about your brand:

→ **[causabi.com](https://causabi.com)** — free public score + deep audit after signup

## Agent skill

[`skills/ai-search-visibility`](skills/ai-search-visibility/SKILL.md) tells Claude Code, Codex CLI, Cursor and other agents when to use this server and how to apply the fixes with the site's real facts. Copy the folder into your agent's skills directory (for Claude Code: `.claude/skills/`).

## Python CLI

Same checks as a standalone CLI: [github.com/SHADRINMMM/causabi-geo](https://github.com/SHADRINMMM/causabi-geo)

```bash
pip install causabi-geo
geo-optimizer analyze example.com
geo-optimizer fix example.com --output ./fixes
```

## License

MIT