# Wingate SEO MCP

Open-source, self-hosted Google Search Console + Google Analytics 4 MCP server for ChatGPT and other MCP clients. Analyze your own SEO data without paying for another SEO dashboard.

Wingate SEO MCP connects an MCP client to Google properties you already control. It combines Search Console performance, GA4 engagement, sitemap and URL Inspection evidence, period comparisons, and deterministic SEO diagnostics in one read-only service.

Publisher: **Wingnut Innovations**  
Version: **0.5.1**  
License: **MIT**

## Why use it?

- Ask questions about your own GSC and GA4 data in natural language.
- Keep credentials and property mappings on infrastructure you control.
- Replace recurring dashboard work with reproducible evidence and calculations.
- Inspect event activity, landing-page engagement, CTR opportunities, ranking changes, decay, and cannibalization.
- Start with a deliberately small, read-only security boundary.

You supply your own Google credentials and grant that identity access only to the properties you want to analyze. Wingate SEO MCP does not include hosted accounts, bundled Google access, paid gates, telemetry, advertising, or subscriptions.

## Read-only MCP tools

The public server exposes exactly 11 tools:

| Tool | Purpose |
|---|---|
| `seo_list_sites` | List locally mapped sites available to the connector |
| `gsc_search_performance` | Query clicks, impressions, CTR, and average position |
| `gsc_compare_periods` | Compare a period with the immediately preceding period |
| `gsc_list_sitemaps` | Review submitted sitemap health |
| `gsc_inspect_url` | Inspect one URL within a locally configured property |
| `ga4_overview` | Review aggregate traffic, engagement, events, and revenue |
| `ga4_events` | Review event counts, key-event attribution, and active users |
| `ga4_landing_pages` | Review landing-page behavior |
| `seo_blended_landing_pages` | Join GSC and GA4 evidence by normalized landing path |
| `seo_find_opportunities` | Find CTR, striking-distance, decay, and cannibalization opportunities |
| `seo_run_audit` | Run the complete deterministic evidence bundle |

There are no Search Console, Google Indexing, GA4 Admin, sitemap-submission, or other write tools in the public server.

## GA4 report-quality diagnostics

GA4 results include report diagnostics as evidence about the returned data. Google may apply thresholding or sampling, and high-cardinality dimensions can be grouped into an `(other)` row. Bounded tool responses also report when more rows are available, while property-quota details are informational only. These caveats do not prove tracking is correct or complete, and Wingate SEO MCP cannot bypass Google's reporting behavior.

`ga4_overview` can optionally add session-level traffic-acquisition evidence without adding another MCP tool:

```json
{
  "siteKey": "example-site",
  "days": 28,
  "includeAcquisition": true,
  "acquisitionLimit": 25
}
```

The default overview makes no acquisition request and returns `acquisition: null`. When enabled, `acquisition` groups rows by session default channel group and session source/medium, uses the same date range and `googleOrganicOnly` scope as the overview, and is limited to 1-100 rows. Its `reportDiagnostics` expose truncation, thresholding, sampling, and quota caveats; GA4 acquisition attribution is not equivalent to Search Console attribution.

## Requirements

- Node.js 20, 22, or 24
- npm
- A Google Cloud project with the required APIs enabled
- A user-supplied Google service-account JSON credential with access to your GSC and GA4 properties
- An MCP client that can reach the local Streamable HTTP endpoint

## Quick start

```bash
git clone https://github.com/aitradesniper-blip/wingate-seo-mcp-public.git wingate-seo-mcp
cd wingate-seo-mcp
npm install
```

Use `.env.example` as a template and set the same environment variables in the shell that starts the commands. The project does not automatically load `.env`. Keep the downloaded service-account JSON outside the repository.

```text
GOOGLE_SERVICE_ACCOUNT_FILE=/absolute/path/to/google-service-account.json
WINGATE_SITES_FILE=./config/sites.local.json
```

The MCP runtime started by `npm start` requires explicit service-account credentials. Set `GOOGLE_SERVICE_ACCOUNT_FILE` (preferred), `GOOGLE_APPLICATION_CREDENTIALS`, or `GOOGLE_SERVICE_ACCOUNT_JSON`. It does not fall back to an attached Google Cloud metadata/workload identity.

Validate credentials and discover accessible properties:

```bash
npm run doctor
npm run discover:google
```

Generate an ignored local site registry using properties returned by discovery:

```bash
npm run setup -- --output config/sites.local.json \
  --gsc sc-domain:example.com \
  --ga4 123456789 \
  --origin https://example.com \
  --key example-site \
  --name "Example Site"
```

Run bounded live reads, then start the server:

```bash
npm run live:smoke -- --site example-site --inspect-origin
npm start
```

The default endpoints are:

```text
http://127.0.0.1:3000/healthz
http://127.0.0.1:3000/mcp
```

See [Google setup](docs/GOOGLE_SETUP.md) and [live onboarding](docs/LIVE_ONBOARDING.md) for a detailed walkthrough.

## Google API setup

Enable these APIs in your Google Cloud project:

- Google Search Console API
- Search Console URL Inspection API
- Google Analytics Data API
- Google Analytics Admin API

Grant the service-account email access to each Search Console property and at least Viewer access to each GA4 property. The runtime requests only:

- `https://www.googleapis.com/auth/webmasters.readonly`
- `https://www.googleapis.com/auth/analytics.readonly`

The Analytics Admin API is used only to discover accessible GA4 properties and web streams. The MCP server does not modify GA4 Admin settings.

## Site mapping

Each local registry entry maps a stable `siteKey` to one Search Console property, an optional GA4 property, and the site's origin. Copy [config/sites.example.json](config/sites.example.json) for the shape, or let `npm run setup` generate and validate `config/sites.local.json`.

Local registries are ignored by Git. Never commit real property mappings if repository readers should not know which sites you operate.

## Connect an MCP client

Start the server and point a Streamable HTTP-capable MCP client at the local `/mcp` endpoint. Use a client-supported local connection or an independently reviewed transport boundary. This repository does not ship an Internet tunnel or authentication layer.

Before sending data, inspect tool discovery and confirm there are exactly 11 tools and every tool is marked read-only. See [MCP client connection](docs/CHATGPT_CONNECTION.md).

## Example questions

- “Which pages lost clicks this month?”
- “Find queries ranking 4–20 with weak CTR.”
- “Which organic landing pages have the best engagement?”
- “Did my lead event fire?”
- “Compare the last 28 days with the previous 28 days.”

## Privacy and security

Wingate SEO MCP has no undisclosed telemetry. It does not send usage analytics to Wingnut Innovations or any third party.

Data leaves your machine or server only when:

- the connector calls Google APIs using the credentials and property access you configured; or
- your configured MCP client sends requests to, and receives results from, this server.

The server binds to `127.0.0.1` by default. Do not expose it directly to the public Internet without adding an independently reviewed authentication and transport boundary. Do not place credentials, local registries, or command output in prompts or source control. See [SECURITY.md](SECURITY.md).

## Troubleshooting

- **Credential file unreadable:** use an absolute path and keep the JSON outside the repository.
- **403 from Google:** enable the relevant API and grant the service-account email access to the property.
- **No GA4 property found:** grant at least Viewer access, then rerun `npm run doctor`.
- **Ambiguous mapping:** provide `--ga4` explicitly; discovery never silently chooses a weak match.
- **No event row:** GA4 observed no matching row for that date/filter scope; absence alone does not diagnose instrumentation.
- **MCP client cannot connect:** confirm `npm start`, `/healthz`, loopback binding, and the client's local-network or separately secured transport configuration.

## Development and validation

```bash
npm run ci
```

This runs syntax checks, TypeScript checks, unit/integration tests, a production build, and MCP discovery. CI targets Node.js 20, 22, and 24.

Docker packaging is intentionally deferred until a small, reviewable image and non-root runtime policy are ready; the Node/npm self-hosting path is the v0.5.0 baseline.

## Roadmap and support

See [the roadmap](docs/ROADMAP.md). Wingate SEO MCP is free and open source. If it saves you time or an SEO-tool subscription, you can optionally support continued development. No funding provider is configured in v0.5.0.

## License, provenance, and independence

Wingate SEO MCP is licensed under the [MIT License](LICENSE). Selected Google client and method mappings were adapted and substantially rewritten from the pinned MIT-licensed upstream documented in [UPSTREAM.md](UPSTREAM.md), [UPSTREAM_IMPORT_MANIFEST.json](UPSTREAM_IMPORT_MANIFEST.json), and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Wingate SEO MCP is an independent project published by Wingnut Innovations. It is not affiliated with, endorsed by, or sponsored by Google or OpenAI. Google Search Console, Google Analytics, GA4, ChatGPT, and OpenAI are trademarks of their respective owners.