Content
# Google Search Console MCP Server
This project provides a Model Context Protocol (MCP) server that allows Claude AI (via the Claude Desktop app) or others to interact with the Google Search Console API. You can use it to query performance data, inspect URLs, check indexing status, and more, directly from your Claude chat (or others).
You can follow me on X [@metehan777](https://x.com/metehan777) and visit my blog [https://metehan.ai](https://metehan.ai)
## Features
Based on the available Google Search Console API endpoints allowed in this project:
* **Sites:** List accessible sites/properties in your Search Console account.
* **Search Analytics:** Fetch search performance data (clicks, impressions, CTR, position) with various filters and dimensions.
* **URL Inspection:** Inspect the status of a specific URL in the Google index, check its indexing status, and request indexing.
* **Sitemaps:** List submitted sitemaps for a site.
* **(Helper)** Get an overall site performance summary (derived from Search Analytics data).
*(Note: Index coverage details and crawl errors beyond what's available in the URL Inspection API are generally not exposed via the Google Search Console API.)*
See the Search Console API capabilities & announcements here: [https://developers.google.com/webmaster-tools/v1/api_reference_index](https://developers.google.com/webmaster-tools/v1/api_reference_index?hl=tr)
## Prerequisites
* **Python:** Version 3.11 or higher.
* **pip:** Python package installer (usually comes with Python).
* **Virtual Environment Tool:** `venv` (recommended, built into Python 3).
* **Google Account:** With access to the Google Search Console properties you want to query.
* **Claude Desktop App:** Installed and running.
## Setup Instructions
1. **Clone or Download:**
Get the project files onto your local machine. If using git:
```bash
git clone https://github.com/metehan777/google-search-console-mcp.git
cd search-console-mcp
```
2. **Create and Activate Virtual Environment:**
It's highly recommended to use a virtual environment to manage dependencies.
```bash
# Create the virtual environment (using the name 'fresh_env' as in previous steps)
python3 -m venv fresh_env
# Activate the environment
# On macOS/Linux:
source fresh_env/bin/activate
# On Windows:
# .\fresh_env\Scripts\activate
```
*(You should see `(fresh_env)` at the beginning of your terminal prompt)*
3. **Install Dependencies:**
Install the required Python packages, including the project itself in editable mode.
```bash
pip install -e .
```
4. **Google Cloud Setup & Credentials:**
* **Enable API:** Go to the [Google Cloud Console](https://console.cloud.google.com/) and create a new project or select an existing one. Enable the "Google Search Console API" for your project.
* **Create OAuth Credentials:**
* Navigate to "APIs & Services" -> "Credentials".
* Click "+ CREATE CREDENTIALS" -> "OAuth client ID".
* If prompted, configure the "OAuth consent screen" (select "External" user type, provide an app name like "Claude GSC Tool", your email, and save).
* For "Application type", select **"Desktop app"**.
* Give it a name (e.g., "Claude Desktop GSC Tool").
* Click "Create".
* **Download `credentials.json`:** After creation, click "DOWNLOAD JSON". Save this file directly into the root of your project directory (`search-console-mcp/`) and ensure it is named exactly `credentials.json`.
* **IMPORTANT:** Make sure `credentials.json` is listed in your `.gitignore` file to avoid accidentally committing it.
5. **Initial Authentication:**
* The first time a tool requiring authentication is run (either manually or via Claude), it will trigger the Google OAuth flow.
* Your web browser should open, asking you to log in to the Google Account that has access to your Search Console properties.
* Grant the requested permissions to the application you configured ("Claude GSC Tool").
* After successful authorization, a `token.json` file will be created in your project directory. This stores your access token. **Do not commit `token.json` if you are going to fork this repo and push/pull it again**.
## Running the Server (Development/Testing)
While the primary use is via Claude Desktop integration, you can test the server directly using `stdio` transport:
The server will start and wait for JSON-RPC messages on standard input/output. You can press `Ctrl+C` to stop it. Logs will be printed to standard error.
## Claude Desktop Integration
To make the tools available in the Claude Desktop app:
1. **Locate Configuration File:** Find the Claude Desktop configuration file. On macOS, it's typically at:
`~/Library/Application Support/Claude/claude_desktop_config.json`
2. **Edit Configuration:** Open the file in a text editor. Add or modify the `mcpServers` section to include an entry for this tool. Use the **absolute path** to the `python3` executable within your virtual environment.
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/Users/username/Downloads"
]
},
"google-search-console": {
"command": "/Users/username/Documents/search-console-mcp/fresh_env/bin/python3",
"args": [
"-m",
"main"
],
"cwd": "/Users/username/Cursor/search-console-mcp"
}
}
}
```
* **Important:** Replace `/Users/username/Documents/search-console-mcp` with the actual absolute path to your project directory on your system in both the `command` and `cwd` fields.
* If you already have other servers in `mcpServers`, just add the `"google-search-console": { ... }` block alongside them.
3. **Restart Claude Desktop:** Close and reopen the Claude Desktop application for the changes to take effect.
## Usage in Claude
Once set up and integrated, you can ask Claude to use the tools. Examples:
* "List my sites in Google Search Console."
* "Get the search performance for example.com for the last 7 days, broken down by query."
* "Inspect the URL https://example.com/my-page on site example.com."
* "Are there any mobile usability issues for example.com?"
* "Submit https://example.com/new-article for indexing on site example.com."
Claude should identify the appropriate tool and execute it via the MCP server. Remember to grant permissions during the initial authentication flow if prompted.
You can contribute or suggest improvements anytime!
