Metadata-Version: 2.4
Name: google-search-console-mcp
Version: 0.10.1
Summary: The GSC 'Intel Engine' for the evolving search landscape. Authoritative visibility governance and AI overview citation analysis via Model Context Protocol.
Project-URL: Homepage, https://github.com/surendranb/google-search-console-mcp
Project-URL: Repository, https://github.com/surendranb/google-search-console-mcp.git
Project-URL: Issues, https://github.com/surendranb/google-search-console-mcp/issues
Author-email: Surendran B <reachsuren@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: google-api-python-client>=2.0.0
Requires-Dist: google-auth-httplib2>=0.1.0
Requires-Dist: google-auth-oauthlib>=0.4.0
Requires-Dist: google-auth>=2.0.0
Requires-Dist: mcp<3,>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="logo.svg" alt="Google Search Console MCP Logo" width="120" />
</p>

# Google Search Console MCP "Intel Engine" 🚀

[![PyPI version](https://badge.fury.io/py/google-search-console-mcp.svg)](https://badge.fury.io/py/google-search-console-mcp)
[![PyPI Downloads](https://static.pepy.tech/badge/google-search-console-mcp)](https://pepy.tech/projects/google-search-console-mcp)
[![GitHub stars](https://img.shields.io/github/stars/surendranb/google-search-console-mcp?style=social)](https://github.com/surendranb/google-search-console-mcp/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/surendranb/google-search-console-mcp?style=social)](https://github.com/surendranb/google-search-console-mcp/network/members)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**The Authority-Based Visibility Governance Tool for the Evolving Search Landscape.**

This is not just a data wrapper. It is a strategic "Intel" engine that transforms raw Google Search Console signals into actionable marketing insights. It is designed for marketers who need to understand their performance in a search landscape increasingly defined by AI Overviews and conversational search. **Compatible with any MCP-compliant AI Agent.**

<p align="center">
  <img src="https://pypi.builditwithai.xyz/api/v1/google-search-console-mcp/banner.svg" alt="PyPI Downloads Breakdown and Trend" width="800" /><br>
  <sub>Analytics powered by <a href="https://pypi.builditwithai.xyz">pypi.builditwithai.xyz</a></sub>
</p>

## 🎯 Authoritative "Intel" Tools

| Tool Name | Actionable Marketing Intel Provided |
| :--- | :--- |
| **`get_search_appearance_audit`** | **Cannibalization Intel.** Detects if you are being used as a "Silent Reference" (high visibility but no clicks) in specialized SERP features. |
| **`get_intent_segmentation`** | **Strategic Audience Intel.** Segments traffic into "Searchers" (Traditional Keywords) vs. "Prompters" (Natural Language/AI Prompts). |
| **`identify_citation_opportunities`** | **Growth Intel.** Finds content that satisfies user intent so well that users don't click. Recommends "Click-Triggers." |
| **`get_technical_citation_audit`** | **Technical Health Overlay.** Cross-checks high-visibility pages with the URL Inspection API to find disqualifying crawl errors. |
| **`get_brand_visibility_summary`** | **Brand Health Intel.** Measures your Brand's "Reference Value" vs its "Destination Value." |
| **`calculate_intent_efficiency`** | **Conversion Intel.** Shows which search intent (Informational/Navigational) is most effectively driving site visits. |

---

## 🚀 Getting Started

### 1. Google Search Console Setup
Before installing the MCP server, you must configure Google Cloud and Search Console access:

**A. Create Service Account:**
1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Create a new project and enable the **Google Search Console API**.
3. Go to **APIs & Services > Credentials** and create a **Service Account**.
4. Create a **JSON Key** for the service account and download it (save as `gsc-key.json`).

**B. Grant Access in Search Console:**
1. Open your JSON key file and copy the `client_email` address.
2. Go to [Google Search Console](https://search.google.com/search-console).
3. Select your property and go to **Settings > Users and Permissions**.
4. Click **Add User**, paste the service account email, and select **Full** permissions.

**C. Identify Your Property URL:**
- For **Domain properties**, use the format: `sc-domain:example.com`
- For **URL-prefix properties**, use the full URL: `https://example.com/`

### 2. Installation
```bash
pip install google-search-console-mcp
```

### 3. Configuration (Universal AI Agent)
Add this to your agent's MCP settings file:
```json
{
  "mcpServers": {
    "gsc-search": {
      "command": "gsc-mcp",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/gsc-key.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}
```

---

## 🛠️ Project Philosophy
This project focuses on **high-leverage data analysis** for modern search:
- **Simplicity First**: Minimum code for maximum insight.
- **Token Efficiency**: Server-side aggregation prevents "Context Length" issues.
- **Authoritative Data**: We only use official Google Search Console API signals. No speculative "AI SEO" hacks.

---

## Telemetry & Privacy
This server sends anonymous usage telemetry (server version, OS, Python version, MCP client name, tool name, latency, error category) to help improve it. It never collects PII, your Search Console data, credentials, or file paths. Opt out any time by setting `DISABLE_TELEMETRY=1`, `DO_NOT_TRACK=1`, `NO_TELEMETRY=1`, or `GSC_MCP_TELEMETRY=false`.

---

## License
MIT License