# GSC MCP

An extensible [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for Google Site Verification and Google Search Console. It uses the MCP Streamable HTTP transport and keeps Google OAuth credentials and tokens local.

## Available tools

| Tool | Purpose |
| --- | --- |
| `get_verification_token` | Get a FILE or META verification token for a URL-prefix site |
| `verify_site` | Verify site ownership after the file or meta tag is live |
| `add_site_to_search_console` | Add a verified URL-prefix property |
| `submit_sitemap` | Submit a sitemap for a property |
| `list_sites` | List Search Console properties |
| `list_sitemaps` | List submitted sitemaps and their status |

## Requirements

- Node.js 20 or newer
- A Google Cloud OAuth Desktop client
- Site Verification API and Search Console API enabled in the Google Cloud project

## Setup

```bash
npm ci
cp .env.example .env
```

Fill `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in `.env`, then generate a strong MCP bearer token:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

Put the generated value in `MCP_AUTH_TOKEN`, authorize Google once, and start the server:

```bash
npm run auth
npm start
```

The endpoints are:

- MCP: `http://127.0.0.1:8787/mcp`
- Health: `http://127.0.0.1:8787/health`

MCP requests must include `Authorization: Bearer <MCP_AUTH_TOKEN>`. To connect a remote MCP client, expose the local endpoint through a trusted HTTPS tunnel and keep bearer authentication enabled.

## Architecture

```text
src/index.js                    runtime composition
src/http-server.js              HTTP transport and bearer auth
src/server.js                   MCP server construction
src/google-client.js            reusable Google OAuth/API client
src/tools/index.js              central tool registry
src/tools/google-search-console.js
                                Search Console tool module
```

To add another MCP capability:

1. Create one registrar module in `src/tools/`.
2. Export a function with the signature `registerFeatureTools(server, dependencies)`.
3. Add that registrar to `src/tools/index.js`.
4. Add contract tests under `test/`.

Keep API clients outside tool modules and inject them as dependencies. This keeps tools testable and prevents credentials from becoming part of the MCP layer.

## Validation

```bash
npm test
npm run security:check
npm run check
```

CI runs the same deterministic checks on every push and pull request.

## Security

`.env`, `token*.json`, `client_secret*.json`, private keys, dependencies, and logs are excluded from Git. The secret check scans only tracked files and fails on blocked credential filenames or high-confidence token patterns. See [SECURITY.md](SECURITY.md).