# growth-mcp

**Is AI ignoring your website?** growth-mcp is an open-source [MCP](https://modelcontextprotocol.io) server that turns Claude, Cursor, or any MCP client into a marketing analyst — starting with the question every marketer is asking in 2026: *can ChatGPT, Perplexity, and Google AI Overviews actually read and cite my site?*

[![CI](https://github.com/abhi725/growth-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/abhi725/growth-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](pyproject.toml)

No API keys. No signup. No LLM calls from the server. Just ask your AI assistant:

> "Audit example.com for AI search readiness"

and get back a 0–100 score with evidence and a prioritized fix list:

```
AI-readiness score: 62/100 (C)
✅ Heading hierarchy is clean
✅ robots.txt does not block AI crawlers
❌ No JSON-LD structured data — AI engines can't parse your entities
❌ No llms.txt — AI crawlers have no guide to your site
❌ Content only appears after JavaScript renders — invisible to most AI crawlers
```

## Why this exists

Search is shifting from "rank on Google" to "get cited by AI." Paid GEO tools cost $100–1000/month; Google's free tools validate markup but don't score or guide. growth-mcp gives you the audit for free, inside the AI assistant you already use — with deterministic, explainable scoring (same URL → same score).

## Quick start

### Claude Code

```bash
claude mcp add growth-mcp -- uvx growth-mcp
```

### Claude Desktop / Cursor

Add to your MCP config (`claude_desktop_config.json` or `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "growth-mcp": {
      "command": "uvx",
      "args": ["growth-mcp"]
    }
  }
}
```

Requires [uv](https://docs.astral.sh/uv/). From source instead: clone this repo and use `"command": "uv", "args": ["run", "--directory", "/path/to/growth-mcp", "growth-mcp"]`.

## Tools

| Tool | What it does |
|---|---|
| `audit_ai_readiness(url)` | 15-check GEO audit → score/100, grade, evidence, fix list |
| `compare_ai_readiness(url_a, url_b)` | You vs. competitor — scores, winner, per-check diff |
| `check_llms_txt(domain)` | Finds and validates `llms.txt` against the [llmstxt.org](https://llmstxt.org) format |
| `audit_onpage_seo(url)` | Title/meta, H1s, canonical, Open Graph, alt coverage, links |

**The 15 AI-readiness checks, across four dimensions:**

- **Access & indexability (30%)** — AI-crawler access in robots.txt (GPTBot/ClaudeBot/PerplexityBot blocked?) · JS-rendered-content risk · noindex/nosnippet directives · XML sitemap
- **Entity & structure (25%)** — JSON-LD structured data · heading hierarchy · title/meta quality · llms.txt presence
- **Citation-ready content (30%)** — FAQ content & FAQPage schema · question-based headings · answer-first structure · lists & tables · factual density (stats/numbers)
- **Trust & E-E-A-T (15%)** — author attribution · freshness dates

**Prompts included:** `full_site_audit`, `compare_with_competitor` — available as slash-commands in clients that support MCP prompts.

## Example prompts

- *"Is my site ready to show up in AI search results? Check leapswitch.com"*
- *"Compare my homepage with competitor.com for AI visibility"*
- *"Does my robots.txt block AI crawlers?"*
- *"Validate the llms.txt on my domain"*

## Run as a hosted endpoint

The same server runs as a remote MCP service over streamable HTTP:

```bash
growth-mcp --transport streamable-http --port 8000
# or
docker build -t growth-mcp . && docker run -p 8000:8000 growth-mcp
```

Deploy it on any VPS or cloud server — for example on [Leapswitch](https://leapswitch.com) — and point any MCP client at `http://your-host:8000/mcp`.

## Design principles

- **Stateless data-plumbing** — the server never calls an LLM; your AI client is the brain.
- **Deterministic scoring** — pure Python, weighted, versioned (`scoring_version` in every result). No flaky AI grades.
- **Safe fetching** — SSRF guard (private/loopback/link-local IPs rejected on every redirect hop), 5 MB response cap, honest User-Agent, timeouts.
- **Compact output** — tools return structured JSON (score + evidence + fix), never raw HTML, so your context window stays clean.
- **Contributor-friendly** — every audit rule is one small file in [`growth_mcp/checks/`](growth_mcp/checks/). Add a function, decorate with `@register`, done.

## Roadmap

- **v0.2 — Connectors (bring your own keys):** Google Search Console top queries, GA4 reports.
- **v0.3 — AI visibility tracking:** run your target prompts against ChatGPT / Perplexity / Gemini APIs and report whether your brand is mentioned and cited vs. competitors — the $100/mo SaaS feature, open source.
- Playwright-based deep rendering (optional extra), sitemap-wide audits, more checks.

## Contributing

New checks are the easiest contribution — see the pattern in [`growth_mcp/checks/base.py`](growth_mcp/checks/base.py). Run the test suite with:

```bash
uv sync --dev
uv run pytest
```

## License & credits

MIT © [Abhishek Ambad](https://github.com/abhi725). Built with support from [Leapswitch Networks](https://leapswitch.com).