mcp-geo

# DigestSEO — AI Visibility MCP for SEO & GEO

[![CI](https://github.com/AKzar1el/mcp-geo/actions/workflows/ci.yml/badge.svg)](https://github.com/AKzar1el/mcp-geo/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/%40digestseo%2Fmcp-geo)](https://www.npmjs.com/package/@digestseo/mcp-geo)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.AKzar1el%2Fmcp--geo-0098FF)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.AKzar1el/mcp-geo)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-F38020?logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/)
[![MCP](https://img.shields.io/badge/MCP-Server-blueviolet)](https://modelcontextprotocol.io/)
[![mcp-geo MCP server](https://glama.ai/mcp/servers/AKzar1el/mcp-geo/badges/score.svg)](https://glama.ai/mcp/servers/AKzar1el/mcp-geo)
[![GitHub stars](https://img.shields.io/github/stars/AKzar1el/mcp-geo?style=social)](https://github.com/AKzar1el/mcp-geo/stargazers)
[![EUR 99 AI Visibility Audit](https://img.shields.io/badge/AI_Visibility_Audit-EUR_99-2ea44f)](https://geo-mcp.digestseo.com/audit)


## Quick Install

Runs locally over stdio with your own API keys — all data stays on your machine (see [Privacy Policy](#privacy-policy)). Set at least one engine key (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `PERPLEXITY_API_KEY`, `SERPAPI_API_KEY`); engines without a key skip gracefully.

**Runtime:** Node.js 22+ (CI exercises Node 22 and 24).

**Claude Desktop / any MCP client (npx):**

```json
{
  "mcpServers": {
    "digestseo": {
      "command": "npx",
      "args": ["-y", "@digestseo/mcp-geo"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "your_key_here"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add --transport stdio digestseo -s user --env GEMINI_API_KEY=your_key_here -- npx -y @digestseo/mcp-geo
```

**Cursor:**

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=digestseo&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBkaWdlc3RzZW8vbWNwLWdlbyJdLCJlbnYiOnsiT1BFTkFJX0FQSV9LRVkiOiIiLCJBTlRIUk9QSUNfQVBJX0tFWSI6IiIsIkdFTUlOSV9BUElfS0VZIjoiIiwiUEVSUExFWElUWV9BUElfS0VZIjoiIiwiU0VSUEFQSV9BUElfS0VZIjoiIn19)

**Kiro (hosted endpoint):**

[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=mcp-geo&config=%7B%22url%22%3A%22https%3A%2F%2Fgeo-mcp.digestseo.com%2Fmcp%22%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)

Uses the hosted OAuth endpoint, so no engine API keys are placed in the Kiro install link.

**Claude Desktop extension (one-click):** download the `.mcpb` bundle from the [latest release](https://github.com/AKzar1el/mcp-geo/releases/latest) and double-click it — Claude Desktop prompts for the API keys.

**First run:** ask your client to *"track acme.com as brand `acme`, then refresh it"* — `track_brand` creates the brand with generated prompts, `refresh_brand` runs the first scan, `check_visibility` shows the scores.

AI agents installing this server: follow [llms-install.md](./llms-install.md). Prefer a remote server with cron auto-refresh? Self-host on Cloudflare Workers below.

---

**mcp-geo** is an open-source **AI visibility tracker** that measures how often your brand is cited by ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews. It's the **GEO** (Generative Engine Optimization) and **AEO** (Answer Engine Optimization) equivalent of Google Search Console — built as an MCP server so you can query your AI visibility data directly inside Claude.ai, Claude Desktop, Claude Code, Cursor, Codex CLI, or any MCP-compatible client.

Canonical product page: [DigestSEO mcp-geo — AI Visibility MCP Server](https://digestseo.com/geo-mcp/)

Engineering case study: [DigestSEO MCP Suite — AI visibility, Search Console, web validation, and trend intelligence](https://tomiseregi.si/projects/digestseo-mcp-suite)

> **Need a client-ready baseline without running the stack yourself?** The [mcp-geo AI Visibility Audit](https://geo-mcp.digestseo.com/audit) is EUR 99 one time: one brand, up to three competitors, 20 buyer-intent prompts, checks across up to five supported AI surfaces where configured providers return usable results, citation evidence, and a prioritized action memo. The open-source package remains free.
>
> **See proof first:** [Open the sample report](docs/demo-report-full.png) generated through mcp-geo to see the output style and evidence depth before requesting the audit.
>
> **Ready to request it?** [Open a prefilled email](mailto:info@tomiseregi.si?subject=mcp-geo%20AI%20Visibility%20Audit%20-%20EUR%2099&body=Hi%20Tomi%2C%0A%0AI%27d%20like%20the%20EUR%2099%20mcp-geo%20AI%20Visibility%20Audit.%0A%0ABrand%2Fdomain%3A%0ACompetitors%20%28up%20to%203%29%3A%0AContext%20or%20priority%20%28optional%29%3A%0A%0ASource%3A%20mcp-geo%20README) with your brand/domain and up to three competitors. No subscription or sales call is required.
>
> **Payment handoff:** After fit and scope are confirmed, I reply with the normal invoice/payment instructions.
>
> **Methodology:** The same 20 buyer-intent prompts are run as a point-in-time diagnostic and reported per engine, with citation/source evidence where available. The audit is an observed snapshot, not a proprietary ranking promise or guaranteed forecast.
>
> **Want the protocol before buying?** [Read the AI Visibility Audit methodology](docs/ai-visibility-audit-methodology.md), including scope, engine coverage, interpretation limits, and what the audit does not claim.

> **Prefer zero setup?** Try the hosted version at [digestseo.com](https://digestseo.com) — managed Cloudflare infra, no API keys to manage, multi-brand, scheduled refresh, web UI. Waitlist now open. [Join waitlist →](https://digestseo.com/#waitlist)

---

## What it produces

Connect via MCP, ask Claude *"Run an AI visibility analysis on [my brand]"*, and within 90 seconds you get a strategist-quality memo grounded in real per-engine data:

[![Example AI visibility report](docs/demo-report-hero.png)](docs/demo-report-full.png)

*[View the full report including content gaps, engine recommendations, and synthesis →](docs/demo-report-full.png)*

The report above was generated by Claude through the digestseo-mcp MCP server. The conversation chained five hosted tools — `visibility.check`, `visibility.compare`, `visibility.citations` (Perplexity + Claude), and `visibility.content_gaps` — to produce a 4-engine analysis with citation excerpts and a 3-recommendation strategy memo.

---

## What's New

### [0.3.3] - September 10, 2026

- **Optional one-time audit:** the open-source package stays free; teams that want a client-ready baseline can request the EUR 99 mcp-geo AI Visibility Audit from the CTA above.
- **Lower-friction request path:** the README now opens a prefilled, source-marked email, while the audit details remain available at `https://geo-mcp.digestseo.com/audit`.

### [0.3.2] — July 27, 2026

- **Published scoped package:** `@digestseo/mcp-geo` with synchronized Worker, MCP Registry, and MCPB metadata.
- **Hosted tool metadata:** `visibility.*` namespaces with typed input/output schemas; local stdio tool names remain flat.
- **Distribution and deployment:** dedicated `mcp-geo-db` D1 configuration, Cursor and Claude Code plugin metadata, and patched production dependency pins.

### [0.3.0] — July 2026

- **Local stdio CLI on npm** (`npx -y @digestseo/mcp-geo`): the same MCP tools backed by a local SQLite database (`~/.digestseo/digestseo.sqlite`) — no Cloudflare account needed. Engines run inline with your own API keys.
- **Local brand-management tools** (CLI only): `track_brand`, `list_brands`, `generate_prompts`. Workers deployments keep these behind the `X-Seed-Secret`-gated `/admin/*` routes.
- **Runtime-agnostic core** (`src/core/`) shared by the Worker and the CLI, with a `Db` contract implemented by D1 and better-sqlite3 adapters. All 0.2.1 accuracy and security fixes carry over to both runtimes.
- **Distribution metadata**: official MCP Registry `server.json`, MCPB desktop extension (`.mcpb` bundle), Dockerfile, `llms-install.md` for AI agents, release-publish workflow.

### [0.2.1] — June 2026

- **Optional `CONNECT_SECRET` gate on the OAuth flow.** By default the OSS build auto-completes `/authorize` for any MCP client that knows your worker URL — anyone who finds the URL can connect and call `visibility.refresh`, spending your engine API credits. Set `CONNECT_SECRET` and the browser step of the connect flow now asks for it before issuing a token. See [SECURITY.md](./SECURITY.md).
- **Accurate citation matching.** Brand/competitor mentions now require word boundaries (`acme` no longer matches "acmeshop"), and linked-citation checks require the exact domain or a subdomain (`notacme.com` no longer counts as a link to `acme.com`).
- **Per-brand `aliases` and `exclude_terms`.** Aliases always count as a mention; exclude terms suppress the bare-word match on the brand name and domain root — so "Monday" the brand stops matching "monday" the weekday, while `monday.com` still counts. Apply `migrations/0005_brand_alias_exclude.sql`; existing brands behave exactly as before.
- **`visibility.history` consistency.** Partially-finished runs now count toward history (matching `visibility.check`'s 0.2.0 behavior), and fully-failed runs no longer show up as fake zero scores.
- **CI + unit tests.** GitHub Actions runs `tsc --noEmit` plus a pure-function unit suite (`npm run test:unit`) covering mention matching, citation extraction, and score aggregation on every push.
- **Docs now recommend OpenAI + Anthropic as the starting engine pair** — the Gemini free tier rate-limits brands with more