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