# GSC MCP Server

Google Search Console MCP Server — a TypeScript [Model Context Protocol](https://modelcontextprotocol.io) server that provides tools for interacting with the Google Search Console API through AI assistants like Claude Desktop.

This is a TypeScript port of the [mcp-gsc](https://github.com/aminforoutan/mcp-gsc) Python server, fully compatible with the MCP specification.

## Features

- **19 MCP Tools** covering all aspects of Google Search Console
- **Service Account authentication** — no browser OAuth flow required
- **Cross-platform** — Windows, macOS, Linux
- **STDIO transport** support
- **Zero-config defaults** — automatically picks up the service account JSON from the `key` folder
- **Safety-first** — destructive operations disabled by default

## Tools Overview

| Category | Tool | Description |
|----------|------|-------------|
| **Properties** | `list_properties` | List all GSC sites you have access to |
| | `get_site_details` | Get verification and ownership info for a site |
| | `add_site` | Add a new property *(destructive — disabled by default)* |
| | `delete_site` | Remove a property *(destructive — disabled by default)* |
| **Analytics** | `get_search_analytics` | Top queries/pages with clicks, impressions, CTR, position |
| | `get_performance_overview` | Summary + daily trend for a time period |
| | `compare_search_periods` | Compare performance between two date ranges |
| | `get_search_by_page_query` | Queries driving traffic to a specific page |
| | `get_advanced_search_analytics` | Advanced filtering, pagination, and explicit current-page sorting |
| **URL Inspection** | `inspect_url_enhanced` | Detailed crawl/index/rich-result status for a URL |
| | `batch_url_inspection` | Inspect up to 10 URLs at once |
| | `check_indexing_issues` | Check multiple URLs for indexing problems |
| **Sitemaps** | `get_sitemaps` | List all sitemaps for a site |
| | `list_sitemaps_enhanced` | Detailed sitemap info with errors and warnings |
| | `get_sitemap_details` | Detailed info for a specific sitemap |
| | `submit_sitemap` | Submit or resubmit a sitemap |
| | `delete_sitemap` | Remove a sitemap *(destructive — disabled by default)* |
| | `manage_sitemaps` | All-in-one: list, details, submit, delete |
| **Info** | `get_capabilities` | List all tools, auth status, and getting started guide |

## Prerequisites

- **Node.js** 18+ (LTS recommended)
- A Google Cloud project with the **Search Console API** enabled
- A **service account** with access to your GSC properties (see below)

## Installation

```bash
# Clone the repository
git clone <repo-url> gsc-mcp
cd gsc-mcp

# Install dependencies
npm install

# Build
npm run build
```

## Authentication Setup

This server uses **Service Account** authentication only.

1. Create a service account in your Google Cloud project
2. Download the JSON key file
3. Add the service account email as a user in GSC for each property

Place the key file in the `key` folder of the project (the server will automatically
pick the first JSON file there), or set the environment variable:

```bash
# Windows (PowerShell)
$env:GSC_CREDENTIALS_PATH = "C:\path\to\service_account_credentials.json"

# macOS / Linux
export GSC_CREDENTIALS_PATH="/path/to/service_account_credentials.json"
```

Credential lookup priority:
1. `GSC_CREDENTIALS_PATH` environment variable (absolute path)
2. The first JSON file in the `key` folder (default)
3. `service_account_credentials.json` in the script directory / current directory

## Claude Desktop Configuration

Edit `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": [
        "C:\\path\\to\\gsc-mcp\\build\\index.js"
      ],
      "env": {}
    }
  }
}
```

If you are not using the `key` folder, set `GSC_CREDENTIALS_PATH` in `env`:

```json
{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["C:\\path\\to\\gsc-mcp\\build\\index.js"],
      "env": {
        "GSC_CREDENTIALS_PATH": "C:\\path\\to\\service_account_credentials.json"
      }
    }
  }
}
```

For macOS/Linux, use forward slashes and the `export`-style environment configuration.

Restart Claude Desktop after saving. You should see the hammer icon in the input box.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GSC_CREDENTIALS_PATH` | (none) | Absolute path to service account credentials JSON |
| `GSC_ALLOW_DESTRUCTIVE` | `false` | Set to `true` to enable add/delete operations |
| `GSC_DATA_STATE` | `all` | `all` (matches GSC dashboard) or `final` (confirmed data only, 2-3 day lag) |

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run (STDIO)
npm start
```

## Project Structure

```
gsc-mcp/
├── src/
│   ├── index.ts    # MCP server entry point + all tool registrations
│   └── auth.ts     # Service account authentication
├── key/            # Default location for service account credentials JSON
├── build/          # Compiled JavaScript output
├── package.json
└── tsconfig.json
```

## Credits

Original Python MCP-GSC server created by [Amin Foroutan](https://aminforoutan.com/).

## License

ISC