# Google Search Console MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for Google Search Console — connect it to Claude Desktop, Claude Code, or any other MCP-compatible client and ask questions about your site's search analytics (clicks, impressions, CTR, position), sitemaps, and indexing status directly in chat.

## What it can do

| Tool | Description |
|---|---|
| `list_sites` | List every property the authenticated account can access |
| `query_search_analytics` | Query clicks, impressions, CTR, and position — grouped by query, page, country, device, or date, with optional filters |
| `list_sitemaps` | List sitemaps submitted for a property |
| `get_sitemap` | Get status/details for one sitemap |
| `submit_sitemap` | Submit a new sitemap |
| `delete_sitemap` | Remove a sitemap |
| `inspect_url` | Run the URL Inspection tool (indexing status, coverage issues, mobile usability) on a single URL |

## Requirements

- Node.js 18+
- A Google account with **Owner or Full user** access to the site(s) in [Google Search Console](https://search.google.com/search-console)

---

## 1. Create a Google Cloud project and enable the API

1. Go to the [Google Cloud Console](https://console.cloud.google.com/) and create a new project (top bar → project dropdown → **New Project**). Give it any name, e.g. `GSC Connection`.

   ![Creating a new Google Cloud project](docs/screenshots/01-create-project.jpg)
2. With that project selected, open **APIs & Services → Library**, search **"Google Search Console API"**, and click **Enable**.

Everything below branches by auth method — pick one.

---

## 2a. Option A — OAuth 2.0 (recommended if this is just for you)

Uses your own Google login, so it automatically sees every property you personally have access to. Requires a one-time browser authorization.

**Configure the consent screen:**

1. Go to **APIs & Services → OAuth consent screen** (in the newer Cloud Console this is under **Google Auth Platform → Branding**, part of a 4-step setup wizard).
2. **App information**: enter an app name (e.g. `GSC MCP Server`) and your email as the support email → **Next**.

   ![OAuth consent screen App Information step](docs/screenshots/05-oauth-consent-branding.jpg)
3. **Audience**: choose **External** → **Next**.
4. **Contact information**: enter your email → **Next**.
5. **Finish**: accept the policy → **Create**.
6. On the **Audience** page that follows, scroll to **Test users → Add users**, and add your own Google account's email. While the app is unpublished ("Testing" status), only test users can complete the login — this is expected and fine to leave as-is indefinitely for personal use.

   ![Adding a test user under Audience settings](docs/screenshots/02-oauth-test-users.jpg)

**Create the OAuth client:**

1. Go to **Clients** (left sidebar) → **Create client**.
2. **Application type: Web application** (not "Desktop" — this project's local auth flow expects a fixed redirect URI, which only the Web application type lets you set).
3. Name it anything, e.g. `GSC MCP`.
4. Under **Authorized redirect URIs**, click **Add URI** and enter exactly:
   ```
   http://localhost:53682/oauth2callback
   ```

   ![Creating the OAuth client ID as a Web application](docs/screenshots/04-create-oauth-client.jpg)
5. Click **Create**, then download the client JSON (via the download icon next to the client in the **Clients** list).
6. Save the downloaded file into this project's folder as `oauth-credentials.json`.

   ![oauth-credentials.json saved in the project folder](docs/screenshots/06-credentials-file-location.jpg)

**Configure and authorize:**

7. Copy `.env.example` to `.env` and set (use **absolute paths** — see the note below):
   ```
   GSC_OAUTH_CREDENTIALS_PATH=/absolute/path/to/google-search-console-mcp-server/oauth-credentials.json
   GSC_OAUTH_TOKEN_PATH=/absolute/path/to/google-search-console-mcp-server/.gsc-token.json
   ```
8. Run the one-time login:
   ```bash
   npm run auth
   ```
   This prints a URL — open it in your browser, log in with the account you added as a test user, and approve access. The CLI saves a token to `.gsc-token.json` and you're done; you won't need to repeat this unless the token is deleted or access is revoked.

> **Why absolute paths?** `.env` paths are resolved relative to the *current working directory of whatever process launches the server* — that's your shell when you run `npm run dev`, but it's a different, unpredictable directory when an app like Claude Desktop spawns the server for you. Relative paths (`./oauth-credentials.json`) can silently fail to resolve in that case, causing an unexplained "no credentials" error. Absolute paths always work regardless of who launches the process.

## 2b. Option B — Service account (no browser login, better for servers/CI)

1. In Cloud Console, go to **APIs & Services → Credentials → Create Credentials → Service account**.
2. Give it any name (e.g. `gsc-mcp`) and click **Done** (no project-level roles needed).
3. Open the new service account → **Keys** tab → **Add Key → Create new key → JSON**. Save the downloaded file into this project's folder, e.g. `gsc-service-account.json`.
4. Copy the service account's **email address** (looks like `gsc-mcp@your-project.iam.gserviceaccount.com`).
5. In [Google Search Console](https://search.google.com/search-console), open the property → **Settings → Users and permissions → Add user** → add the service account's email as a **Full** user. Repeat for every property you want this server to see.
6. In `.env` (absolute path, same reasoning as above):
   ```
   GSC_SERVICE_ACCOUNT_KEY_PATH=/absolute/path/to/google-search-console-mcp-server/gsc-service-account.json
   ```

---

## 3. Install and build

```bash
git clone https://github.com/wyattxmgmt/google-search-console-mcp-server.git
cd google-search-console-mcp-server
npm install
npm run build
```

(You should already have `.env` set up from section 2a or 2b above.)

---

## 4. Connect it to an MCP client

### Claude Desktop

The current Claude Desktop app manages local MCP servers under **Settings → Developer → Local MCP servers**, *not* under **Settings → Connectors** (Connectors there is for remote/hosted MCP servers reachable over HTTPS — a locally-run server like this one won't show up there).

1. Open **Settings → Developer → Local MCP servers → Edit Config**. This opens `claude_desktop_config.json` directly.
2. Add a `mcpServers` entry (merge with whatever's already in the file — don't replace it):
   ```json
   {
     "mcpServers": {
       "gsc": {
         "command": "node",
         "args": [
           "--env-file=/absolute/path/to/google-search-console-mcp-server/.env",
           "/absolute/path/to/google-search-console-mcp-server/dist/index.js"
         ]
       }
     }
   }
   ```
3. Save, then **fully quit** Claude Desktop (not just close the window — use the tray/taskbar icon) and reopen it.
4. Check **Settings → Developer → Local MCP servers** again — `gsc` should show status **running**.

   ![gsc server showing status running under Local MCP servers](docs/screenshots/03-desktop-local-mcp-servers.jpg)

### Claude Code

Copy `.mcp.json.example` to `.mcp.json` in this project and fill in the absolute path:
```json
{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["--env-file=.env", "dist/index.js"],
      "cwd": "/absolute/path/to/google-search-console-mcp-server"
    }
  }
}
```
Open Claude Code in this directory — it'll prompt you to approve the project-scoped `gsc` server on first load. To make it available in every session regardless of directory, register it globally instead:
```bash
claude mcp add gsc --scope user -- node --env-file=/absolute/path/to/google-search-console-mcp-server/.env /absolute/path/to/google-search-console-mcp-server/dist/index.js
```

### Any other MCP client

The server speaks standard MCP over stdio — point your client at `node dist/index.js` with the same environment variables set (or `--env-file`), and it will work the same way.

---

## Example prompts once connected

- "List my Search Console properties"
- "What were my top 20 queries for example.com over the last 28 days?"
- "Compare clicks by device for example.com in July vs June"
- "Is https://example.com/some-page indexed? Run a URL inspection."
- "Submit https://example.com/sitemap.xml as a new sitemap"

## Troubleshooting

- **"No credentials configured"** — you need exactly one of `GSC_SERVICE_ACCOUNT_KEY_PATH` or `GSC_OAUTH_CREDENTIALS_PATH` set in `.env`.
- **"No cached OAuth token found"** — run `npm run auth` first.
- **Works with `npm run dev` but fails/times out when launched by Claude Desktop** — almost always relative paths in `.env`. Switch to absolute paths (see the callout in [2a](#2a-option-a--oauth-20-recommended-if-this-is-just-for-you)).
- **Empty results from `list_sites`** — the account/service-account tied to your credentials hasn't been added as a user on any property in Search Console.
- **403 errors on a specific site** — double check the exact `siteUrl` format Search Console uses for that property (e.g. `sc-domain:example.com` for domain properties vs. `https://example.com/` for URL-prefix properties) — see it via `list_sites`.
- **Google shows "app isn't verified" / blocks login** — expected while the OAuth consent screen is in "Testing" status. Make sure the Google account you're logging in with was added under **Audience → Test users**.

## Development

```bash
npm run dev    # run directly with tsx, no build step
npm run build  # compile to dist/
```

## License

MIT