SEO Console

seo-mcp

seo-mcp is a stdio Model Context Protocol server for Google Search Console, PageSpeed Insights, and on-page SEO audits. It gives MCP clients forty-three tools covering verified Search Console properties and the other places products get discovered, the App Store, Google Play, WordPress.org, Google Ads, and real-user Core Web Vitals, while keeping the HTML audit, PageSpeed, IndexNow, keyword ideas, and WordPress.org tools usable without Google service account credentials. Every tool also runs from the command line, so a result can be written to a file instead of into a model's context, and snapshot records Search Console, the App Store, Google Play and WordPress.org at one moment so a later run can diff against it.

https://github.com/user-attachments/assets/66bbd628-d267-421f-9400-633b696bbd53

Requirements

• Node.js 20.18.1 or newer
• gcloud only if you use the setup wizard

What else you need depends on which tools you use. The setup wizard covers Search Console and PageSpeed; the App Store, Google Play, and Chrome UX Report tools each need a credential you create yourself.

Install and build

npm install

npm run build

Run the local server with:

node /absolute/path/to/seo-mcp/dist/index.js

The package is published on npm as seo-console-mcp; it installs a command named seo-mcp. An MCP client can launch it through:

npx -y seo-console-mcp

The running server uses stdout exclusively for the MCP wire protocol. Diagnostics are written to stderr.

Setup wizard

From a local checkout:

npm run setup

Or with npx:

npx -y seo-console-mcp setup

For an unattended project choice or a custom key location:

seo-mcp setup --project my-seo-project --key /absolute/path/seo-mcp.key.json

The wizard also offers an optional PageSpeed Insights API key for higher quota. It is opt-in: use --pagespeed-key to create one without a prompt, or --no-pagespeed-key to skip the prompt explicitly. Non-interactive runs skip it unless --pagespeed-key is provided.

The wizard is safe to rerun. It:

1. Checks for gcloud. If it is absent, it prints manual instructions and exits successfully without changing anything.
2. Uses the active authenticated account or runs gcloud auth login.
3. Uses the current project, a supplied --project, or asks for a project ID. It creates the project if it does not exist and selects it.
4. Enables searchconsole.googleapis.com, pagespeedonline.googleapis.com, and siteverification.googleapis.com.
5. Reuses or creates the seo-mcp service account.
6. Reuses an existing key or creates seo-mcp.key.json.
7. Optionally creates a project-scoped API key restricted to PageSpeed Insights.
8. Prints the required Search Console permission step and ready-to-copy client configurations.

The wizard never prints the service account key contents. When PageSpeed key creation is requested and succeeds, it prints that key once in the final client configuration. The generated *.key.json filename is ignored by Git.

Granting the service account Search Console access

The Search Console API has no endpoint for adding a user to a property, so the service account has to become a verified owner of the domain itself. There are two ways to do that.

Automated (Cloudflare DNS)

If the domain's DNS is on Cloudflare, verify does the whole thing: it asks Google for a verification token, writes the TXT record through the Cloudflare API, waits for verification, and registers the property.

export CLOUDFLARE_API_TOKEN=...   # a token scoped to Zone.DNS:Edit for the zone

seo-mcp verify getpsst.app another-domain.com

The token can also be passed with --cf-token, and the key path with --credentials (otherwise GOOGLE_APPLICATION_CREDENTIALS / SEO_MCP_CREDENTIALS is used). The command is idempotent: the TXT record is left in place (Google re-checks it), so re-running a domain is safe. Leave the record in DNS or ownership is lost.

verify reads the token from CLOUDFLARE_API_TOKEN or CF_API_TOKEN (or --cf-token) and never stores or logs it, so any secret store that can export an environment variable works. The token needs Zone -> DNS -> Edit and Zone -> Zone -> Read (the "Edit zone DNS" template), scoped to the zones you verify. To keep it out of shell history:

macOS (Keychain):

security add-generic-password -a "$USER" -s cloudflare-dns-edit -l "Cloudflare DNS Edit" -U -w   # store once, hidden prompt

CLOUDFLARE_API_TOKEN=$(security find-generic-password -s cloudflare-dns-edit -w) seo-mcp verify example.com

Linux (libsecret, or pass):

secret-tool store --label="Cloudflare DNS Edit" service cloudflare-dns-edit   # store once, hidden prompt

CLOUDFLARE_API_TOKEN=$(secret-tool lookup service cloudflare-dns-edit) seo-mcp verify example.com

Windows (PowerShell SecretManagement):

Set-Secret -Name cloudflare-dns-edit -Secret (Read-Host -AsSecureString)   # store once, hidden prompt

$env:CLOUDFLARE_API_TOKEN = Get-Secret -Name cloudflare-dns-edit -AsPlainText; seo-mcp verify example.com

Manual

Add the service account as an owner in the Search Console UI:

Search Console -> your property -> Settings -> Users and permissions -> Add user

seo-mcp@PROJECT_ID.iam.gserviceaccount.com -> Owner

Use the exact service account email printed by the wizard. Owner access is needed because submit_sitemap is a write operation.

Manual Google Cloud fallback

If gcloud is unavailable, create the credentials manually or run these commands after installing it:

gcloud auth login

gcloud projects create YOUR_PROJECT_ID gcloud config set project YOUR_PROJECT_ID gcloud services enable searchconsole.googleapis.com pagespeedonline.googleapis.com siteverification.googleapis.com gcloud iam service-accounts create seo-mcp --display-name="SEO MCP" gcloud iam service-accounts keys create ./seo-mcp.key.json \ --iam-account=seo-mcp@YOUR_PROJECT_ID.iam.gserviceaccount.com

If the project already exists, skip gcloud projects create. Then grant the service account Search Console access (see above) and configure the absolute key path in the MCP client.

Authentication

The Search Console tools use google.auth.GoogleAuth with both scopes:

• https://www.googleapis.com/auth/webmasters
• https://www.googleapis.com/auth/webmasters.readonly

Credential lookup order is:

1. --credentials /absolute/path/key.json
2. SEO_MCP_CREDENTIALS
3. GOOGLE_APPLICATION_CREDENTIALS
4. ~/.config/seo-mcp/seo-mcp.key.json (or $XDG_CONFIG_HOME/seo-mcp/...) if it exists. This is the default location the setup wizard writes to, so a standard install needs no configuration.

For example:

node dist/index.js --credentials /absolute/path/seo-mcp.key.json

pagespeed is public and does not use the service account. Set SEO_MCP_PAGESPEED_KEY or pass apiKey to that tool for a higher PageSpeed Insights quota. seo_audit, audit_site, and indexnow_submit also need no Google credentials; indexnow_submit instead takes an IndexNow key via key or SEO_MCP_INDEXNOW_KEY. keyword_ideas only needs them when siteUrl is passed for the Search Console cross-reference. App Store Sales and Trends reads SEO_MCP_ASC_VENDOR_NUMBER. The Chrome UX Report tools read SEO_MCP_CRUX_KEY, falling back to SEO_MCP_PAGESPEED_KEY when the same key is allowed to call chromeuxreport.googleapis.com. snapshot, list_snapshots and compare_snapshots keep their documents in SEO_MCP_SNAPSHOT_DIR, defaulting to ~/.config/seo-mcp/snapshots, and cannot read or write outside it. The table under Requirements maps every tool to what it needs.

Security model

• Verifying a domain makes the service account a verified Owner. Owners can change Search Console settings and submit removal (deindex) requests, so treat the key as a sensitive credential even though most tools here only read.
• Keep the key local. It lives at the GOOGLE_APPLICATION_CREDENTIALS path (chmod 600 recommended). Never bundle it in a published package, a container image, or a CI secret store. If it leaks, anyone with it has owner control of every verified property.
• Leave the `google-site-verification` TXT record in DNS. Google re-checks it; deleting it revokes ownership.
• No secret is logged. The wizard and verify print credential paths only, never key or token contents.
• Revoking is easy. Relinquish ownership from the Search Console UI (or siteVerification.webResource.delete), and rotate the key with gcloud iam service-accounts keys delete.
• `seo_audit` only fetches public hosts. The target URL and every redirect hop is resolved and refused if it lands on a loopback, private, link-local, or other non-public address, so a model cannot be steered into fetching internal services or cloud metadata. The address is validated again at connection time (the socket is pinned to the validated address), so a DNS-rebinding host cannot present a public address at validation and a private one at connect. Set SEO_MCP_ALLOW_PRIVATE_HOSTS=1 to audit internal or staging hosts you trust. This is not a substitute for network-level isolation; run the server behind egress controls if you audit untrusted URLs on a host with reachable internal services.

Claude Code plugin

This repo is also a Claude Code plugin that bundles the MCP server and adds three slash commands over it. From Claude Code:

/plugin marketplace add ibrahimhajjaj/seo-console-mcp

/plugin install seo-console@verdelic

It registers the MCP server (via npx -y seo-console-mcp) and adds:

• /seo-console:triage : full property triage with a prioritized action plan
• /seo-console:content : content to create or improve, backed by Search Console data
• /seo-console:launch : pre-launch / launch SEO readiness check

The server finds your service-account key automatically at the default location (~/.config/seo-mcp/seo-mcp.key.json, where the setup wizard writes it), so no configuration is needed for a standard install. For a key elsewhere, set GOOGLE_APPLICATION_CREDENTIALS (and SEO_MCP_PAGESPEED_KEY for higher PageSpeed quota) in the environment Claude Code runs in. The `s