# MCP Comprehensive Guide (/docs/claude-mcp)

Welcome to the **RankZero Model Context Protocol (MCP)** guide. This MCP server connects Claude directly to your RankZero account securely, allowing you to interface with your SEO data, Google Analytics 4, Google Search Console, AI visibility tracking, and competitors without leaving the chat.

## Installation & Setup

Connecting RankZero to Claude works identically whether you use the **Claude Web Interface** or the **Claude Desktop App**. You do *not* need to manually edit config files.

1. Navigate to the **Integrations** page via the left-hand sidebar menu in RankZero.
2. Under the **Claude** Integration card, click **Connect Claude**.
3. A dialog will prompt you to add a **Custom Connector** in Claude. Open the Claude app or website as instructed.
4. In Claude's Custom Connector settings, enter `RankZero` as the name and paste the **MCP URL** provided on the RankZero integration page.
5. Click **Save**, then click the **Connect** button on the newly created RankZero connector in Claude.
6. Claude will ask you to authorize the connection. Approve the access.
7. You're connected! You can immediately start using RankZero's tools in your active chat.

***

## Core Concepts

**1. The "Active Brand" Context**
Almost all tools in this MCP are designed to be context-aware. If you use the `set_active_brand` tool first, you do not need to constantly specify the brand ID or name for subsequence queries (like `get_brand_overview` or `get_ga4_report`). The MCP remembers what you are currently looking at!

**2. Smart Identification**
You don't need to know raw UUIDs (though they work). You can refer to brands simply by their domain (`acme.com`), their name (`Acme`), or even their index number from the latest `list_brands` output.

***

## 🛠️ Available Tools

Tools are active functions Claude can call to query your data live or trigger actions.

### 1. `list_brands`

* **Purpose:** Lists up to 20 brands you have access to.
* **Arguments:**
  * `search` (optional): Filter by name or domain.
* **Notes:** Smartly sorts by exact matches, default status, and whether the brand has active GA4/GSC connections.

### 2. `set_active_brand`

* **Purpose:** Locks a specific brand into memory as your active conversational context.
* **Arguments:**
  * `brand` (required): The ID, name, or domain of the brand.

### 3. `get_brand_overview`

* **Purpose:** Pulls top-level summary metrics (Rank, Visibility Percentage, Total Citations).
* **Arguments:**
  * `brand` (optional): Omit to use the active brand.
  * `period` (optional): `24h`, `7d`, `30d`, or `90d`. Default is `7d`.

### 4. `get_brand_competitors`

* **Purpose:** Fetches the list of tracked competitors configured for the brand.
* **Arguments:**
  * `brand` (optional): Omit to use the active brand.

### 5. `get_ai_mentions`

* **Purpose:** Views how often the brand is specifically mentioned in AI Search Engines across tracked queries.
* **Arguments:**
  * `brand` (optional): Omit to use the active brand.
  * `period` (optional): The time window to aggregate. Default `7d`.

### 6. `get_ga4_report`

* **Purpose:** Live queries Google Analytics 4 for connected brands.
* **Arguments:**
  * `brand` (optional)
  * `startDate`, `endDate` (optional): E.g., `30daysAgo`, `yesterday`, or `YYYY-MM-DD`.
  * `dimensions` (optional): E.g., `date`, `sessionDefaultChannelGroup`, `pagePath`.
  * `metrics` (optional): E.g., `sessions`, `totalUsers`, `eventCount`.

### 7. `get_gsc_performance`

* **Purpose:** Live queries Google Search Console for traditional SEO performance.
* **Arguments:**
  * `brand` (optional)
  * `startDate`, `endDate` (optional)
  * `dimensions` (optional): Array including `date`, `query`, `page`, `country`, `device`.

### 8. `list_tracked_prompts`

* **Purpose:** Browses the RankZero database of common prompts/queries for your industry.
* **Arguments:**
  * `search` (optional)
  * `page` (optional): For pagination.

### 9. `search_knowledge_base`

* **Purpose:** Performs a semantic vector-search across your site's integrated knowledge base.
* **Arguments:**
  * `query` (required): The natural language question.

***

## 🎭 Available Prompts

Prompts are predefined playbooks Claude can execute. You can invoke these directly via the Claude UI ("Attach Prompt") to kickstart multi-step workflows.

### 1. `analyze-brand`

**What it does:** Automatically queries `get_brand_overview`, `get_brand_competitors`, and `get_ai_mentions` back-to-back to generate a comprehensive SWOT-style analysis of your current visibility.

### 2. `competitor-deep-dive`

**What it does:** Fetches your competitors and then intelligently uses `search_knowledge_base` and other tools to compare their visibility strategy against yours.

### 3. `generate-content-ideas`

**What it does:** Uses `list_tracked_prompts` and `get_gsc_performance` to identify what users are asking vs. what you are ranking for, producing 5 high-impact content ideas optimized for AI Overviews.

***

## 📄 Available Resources

Resources are static context files you can "attach" to your Claude conversation to inject data directly without calling a tool.

1. `active-brand-overview` (`brand://active/overview`): Instantly attaches the 7-day high-level metrics of your active brand into the prompt context.
2. `brand-overview` (`brand://{id}/overview`): Instantly attaches the metrics for a specific brand UUID.

(Note: In Claude, you can simply type `/` and select these resources to drop them directly into your context window).

***

## 🚀 Common Use Cases

### Scenario A: Monthly Reporting

**You:** "Please run the `analyze-brand` prompt for acme.com."
**Claude:** Implicitly sets acme.com as active. Gathers the 7d overview, pulls the competitors, and tracks AI mentions, then synthesizes a beautiful markdown report you can copy-paste.

### Scenario B: Content Strategy

**You:** "I need new blog topics for my active brand. Run `generate-content-ideas`."
**Claude:** Finds your top-ranking traditional SEO queries from GSC, maps them against what people actually ask AI bots (using prompt suggestions), and spots the gaps where you need content.

### Scenario C: Traffic Drops

**You:** "Did our GA4 traffic drop on relative.com last week compared to the week before?"
**Claude:** Invokes `get_ga4_report` twice using relative date strings, compares the `sessions`, and provides an instant diagnostic.

### Scenario D: Portfolio Triage

**You:** "I have several brands tracking. Tell me which of my brands needs the most attention right now."
**Claude:** Lists out your active brands, polls quick overviews for them, and intelligently grades them to tell you which one has the largest drop in AI citations or visibility.

***

## ❓ Frequently Asked Questions

**Q: Do I need to be an Admin to use this?**
A: No! The MCP respects Organization permissions. You can only query brands that you personally own, or brands that are shared with your Clerk Organization team.

**Q: Why do I get an error when running GA4 or GSC tools?**
A: Those tools require your brand to have an active, authenticated OAuth connection to Google in the RankZero web dashboard. If the brand isn't connected, the tool will gracefully let Claude know.

**Q: Does it charge me API credits?**
A: Data pulled from Supabase, GA4, and GSC via the MCP tools does not currently incur extra "AI platform credits" from RankZero, though standard rate limits apply. (Note: using Claude itself consumes your normal Claude usage limits).

**Q: How do I find a brand's exact ID?**
A: You rarely need to! Just use the `list_brands` tool and tell Claude the name or domain. But if you must, the ID is returned in the table output of `list_brands`.