SEO MCP PRO

A Model Context Protocol (MCP) server that provides Claude with 121 tools for website operations, Google Marketing, SEO, performance analysis, security auditing, monitoring, accessibility testing, and more.

---

Table of Contents

• Overview
• Free vs Pro
• Quick Start
• Tool Modules
• Configuration
• Claude Desktop Integration
• Web Dashboard (Pro)
• Dashboard REST API
• Architecture
• Commands
• OAuth Token Helper
• License

---

Overview

seo-mcp-pro is a comprehensive MCP server built with TypeScript in strict mode. It connects Claude to the full spectrum of website management tasks -- from Google Analytics reporting and Tag Manager configuration to SSL analysis, Core Web Vitals monitoring, and WCAG accessibility audits.

• 121 tools across 17 modules
• Zero external runtime frameworks -- uses node:http for the optional dashboard
• Built-in credential management with AES-256-GCM encryption (Pro)
• Per-service rate limiting and in-memory caching

---

Free vs Pro

SEO MCP PRO follows a hybrid open source model. The core MCP tools are free and open source. Advanced reporting, the web dashboard, and credential management require a Pro license.

Feature	Free	Pro
Google Analytics 4 (GA4) tools	Yes	Yes
Google Tag Manager (GTM) tools	Yes	Yes
Google Search Console (GSC) tools	Yes	Yes
Google Ads tools	Yes	Yes
Google Business Profile tools	Yes	Yes
Indexing API tools	Yes	Yes
PageSpeed Insights / Lighthouse	Yes	Yes
Core Web Vitals / CrUX	Yes	Yes
Security auditing (SSL, headers, Safe Browsing)	Yes	Yes
SEO technical (robots, sitemaps, canonicals, etc.)	Yes	Yes
Monitoring (uptime, DNS, certificates)	Yes	Yes
Accessibility (WCAG, contrast, images)	Yes	Yes
Cloudflare integration	Yes	Yes
Utilities (tech detection, broken links, WHOIS)	Yes	Yes
Dashboard overview tool	Yes	Yes
Site Health Report (report_site_health)	--	Yes
SEO Audit Report (report_seo_audit)	--	Yes
Executive Summary (report_executive_summary)	--	Yes
Web Dashboard (browser UI on port 3737)	--	Yes
Encrypted Credential Store (AES-256-GCM)	--	Yes
SSE Real-time Monitoring	--	Yes

Activating Pro

Set your license key as an environment variable:

SEO_MCP_PRO_KEY=SMCP-XXXX-XXXX-XXXX-XXXX

Or add it to your .env file. The server logs the active tier on startup.

---

Quick Start

Install from npm

# Run directly with npx (no install needed)
npx seo-mcp-pro

# Or install globally
npm install -g seo-mcp-pro
seo-mcp-pro

Install from source

git clone https://github.com/bypixels/SEO-MCP-PRO.git
cd SEO-MCP-PRO
pnpm install
pnpm build
pnpm start

Development

pnpm dev         # Development mode with hot reload

---

Tool Modules

The server organizes its tools into 17 modules spanning 14 core categories:

Module	Description	Example Tools
Google Tag Manager	Accounts, containers, workspaces, tags, triggers, variables, versions	gtm_list_containers, gtm_create_tag, gtm_publish_version
Google Analytics 4	Accounts, properties, reports, realtime, funnels, custom dimensions/metrics, audiences, data streams, conversion events	ga4_run_report, ga4_run_realtime_report, ga4_run_funnel_report
Google Search Console	Sites, performance queries, top queries/pages, sitemaps, URL inspection, coverage	gsc_query_performance, gsc_top_queries, gsc_inspect_url
Google Ads	Customers, campaigns, ad groups, keywords, budgets, performance, search terms, keyword ideas	ads_list_campaigns, ads_create_campaign, ads_get_keyword_ideas
Google Business Profile	Accounts, locations, reviews, posts, insights, media	gbp_list_locations, gbp_reply_review, gbp_create_post
Indexing API	Submit URLs for indexing, check status, batch operations	indexing_publish, indexing_get_status, indexing_batch_publish
PageSpeed Insights	Page performance analysis via PSI API	psi_analyze
CrUX	Chrome UX Report data queries and historical trends	crux_query, crux_history
Core Web Vitals	LCP, INP, CLS aggregate reports	cwv_report
Lighthouse	Full Lighthouse audits via PSI API	lighthouse_audit
Security	SSL analysis, security headers, Safe Browsing, comprehensive audits	security_ssl_analyze, security_headers_check, security_audit
SEO Technical	Robots.txt, sitemaps, canonicals, redirects, structured data, headings, meta tags	seo_robots_analyze, seo_sitemap_analyze, seo_structured_data
Monitoring	Uptime, response time, DNS lookup/propagation, certificate checks	monitor_check_uptime, monitor_dns_lookup, monitor_certificate
Accessibility	WCAG audits, contrast checking, image alt text validation	a11y_audit, a11y_check_contrast, a11y_check_images
Utilities	Tech stack detection, broken link scanning, WHOIS, headers, screenshots	util_tech_detection, util_broken_links, util_whois_lookup
Cloudflare	Zones, DNS records, analytics, cache purge, firewall events	cf_get_zones, cf_create_dns_record, cf_purge_cache
Reports	Aggregated site health, SEO audit, executive summary	report_site_health, report_seo_audit, report_executive_summary

---

Configuration

All configuration is handled through environment variables. Create a .env file in the project root:

SEO MCP PRO License

Variable	Description
SEO_MCP_PRO_KEY	Pro license key (SMCP-XXXX-XXXX-XXXX-XXXX)

Google OAuth 2.0

Variable	Description
GOOGLE_CLIENT_ID	OAuth 2.0 client ID
GOOGLE_CLIENT_SECRET	OAuth 2.0 client secret
GOOGLE_REDIRECT_URI	OAuth redirect URI
GOOGLE_REFRESH_TOKEN	OAuth refresh token

Google Service Account

Variable	Description
GOOGLE_SERVICE_ACCOUNT_KEY_FILE	Path to service account JSON key file
GOOGLE_SERVICE_ACCOUNT_IMPERSONATE	Email address for domain-wide delegation

API Keys

Variable	Description
GOOGLE_PAGESPEED_API_KEY	PageSpeed Insights API key
GOOGLE_SAFE_BROWSING_API_KEY	Safe Browsing API key

Google Ads

Variable	Description
GOOGLE_ADS_DEVELOPER_TOKEN	Google Ads API developer token
GOOGLE_ADS_LOGIN_CUSTOMER_ID	Manager account customer ID

Cloudflare

Variable	Description
CLOUDFLARE_API_TOKEN	Cloudflare API token (preferred)
CLOUDFLARE_EMAIL	Cloudflare account email (legacy auth)
CLOUDFLARE_API_KEY	Cloudflare global API key (legacy auth)

Dashboard (Pro)

Variable	Description	Default
DASHBOARD_ENABLED	Enable the web dashboard	false
DASHBOARD_PORT	Dashboard HTTP port	3737
DASHBOARD_API_KEY	API key for dashboard access	--
DASHBOARD_AUTH_REQUIRED	Require authentication for dashboard	false

---

Claude Desktop Integration

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "seo-mcp-pro": {
      "command": "npx",
      "args": ["-y", "seo-mcp-pro"],
      "env": {
        "GOOGLE_PAGESPEED_API_KEY": "your-api-key",
        "SEO_MCP_PRO_KEY": "SMCP-XXXX-XXXX-XXXX-XXXX"
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "seo-mcp-pro": {
      "command": "node",
      "args": ["/path/to/SEO-MCP-PRO/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_PAGESPEED_API_KEY": "your-api-key"
      }
    }
  }
}

Once configured, Claude will have access to all available tools. Ask Claude to analyze your website's performance, check SEO issues, audit security headers, or manage your Google Marketing stack -- all through natural language.

---

Web Dashboard (Pro)

The server includes an optional self-contained web dashboard for browser-based access to all tools and reports. Requires a Pro license.

SEO_MCP_PRO_KEY=SMCP-... pnpm dashboard

Or set DASHBOARD_ENABLED=true and SEO_MCP_PRO_KEY in your .env file and run pnpm start.

The dashboard is available at http://localhost:3737 and provides:

• Tool browser -- Browse and execute all available tools
• Site reports -- Site health, SEO audit, and executive summary reports
• Real-time monitoring -- Server-Sent Events for live status updates
• Credential management -- Save and manage API keys through the UI (AES-256-GCM encrypted at rest)
• Status overview -- Authentication state, cache statistics, rate limit status

---

Dashboard REST API

When the dashboard is enabled (Pro), the following HTTP endpoints are available:

Health and Status

Method	Endpoint	Description
GET	/api/health	Server health check
GET	/api/status/auth	Authentication status
GET	/api/status/cache	Cache statistics
GET	/api/status/rate-limits	Rate limit status per service

Tools and Reports

Method	Endpoint	Description
GET	/api/tools	List all available tools
POST	/api/tool/:name	Execute a tool (JSON body = tool input)
GET	/api/dashboard?url=X	Dashboard overview for a URL
GET	/api/report/site-health?url=X	Site health report
GET	/api/report/seo-audit?url=X	SEO audit report

Settings and Credentials

Method	Endpoint	Description
GET	/api/settings/schema	Configuration schema
GET	/api/settings/credentials	Retrieve saved credentials
POST	/api/settings/credentials	Save credentials
POST	/api/settings/credentials/validate	Validate credentials

Monitoring

Method	Endpoint	Description
GET	/api/sse?url=X	Server-Sent Events stream for real-time monitoring

---

Architecture

src/
├── index.ts                  # Entry point
├── server.ts                 # MCP server setup and tool registration
├── licensing/                # License management (free vs pro)
│   ├── index.ts              # Key validation, isPro(), getLicenseTier()
│   └── tiers.ts              # Pro tool and feature definitions
├── auth/                     # Authentication layer
│   ├── oauth.ts              # Google OAuth 2.0 flow
│   ├── service-account.ts    # Service account authentication
│   └── token-manager.ts      # Automatic token refresh
├── tools/                    # 14 tool modules
│   ├── google/               # GTM, GA4, GSC, Ads, Business Profile, PageSpeed, Indexing
│   ├── performance/          # Core Web Vitals, CrUX, Lighthouse
│   ├── security/             # SSL, headers, Safe Browsing
│   ├── seo-technical/        # Structured data, robots, sitemaps, canonicals
│   ├── accessibility/        # WCAG audits, contrast checking
│   ├── monitoring/           # Uptime, DNS, certificates
│   ├── integrations/         # Cloudflare
│   ├── utilities/            # Screenshots, tech detection, broken links
│   └── reports/              # Site health, SEO audit, executive summary
├── dashboard/                # Optional HTTP dashboard (Pro)
│   ├── http-server.ts        # node:http server (zero frameworks)
│   ├── routes/               # API, SSE, and settings route handlers
│   ├── services/             # Credential store (AES-256-GCM), data orchestration
│   └── ui/                   # Self-contained HTML dashboard
├── utils/                    # Shared utilities
│   ├── rate-limiter.ts       # Per-service rate limiting (bottleneck)
│   ├── cache.ts              # In-memory + file cache
│   └── logger.ts             # Structured JSON logging (winston)
├── config/                   # Google API scopes, default values
└── types/                    # TypeScript type definitions

Design Principles

• Zod validation on all tool inputs and outputs
• Per-service rate limiting via bottleneck (e.g., GTM: 50 req/min, GA4: 100 req/min, GSC: 1200 req/day)
• In-memory caching with 5-minute TTL (1000-item limit) and file cache fallback (1-hour TTL)
• Structured logging with Winston in JSON format
• Automatic token refresh for all Google API interactions
• stdio transport for Claude Desktop; optional HTTP transport for the dashboard

---

Commands

Command	Description
pnpm install	Install dependencies
pnpm build	Build with tsup (ESM)
pnpm start	Run the MCP server (stdio transport)
pnpm dashboard	Run with web dashboard enabled (Pro)
pnpm dev	Development mode with hot reload
pnpm test	Run tests with vitest
pnpm lint	Lint with ESLint
pnpm typecheck	TypeScript type checking

---

OAuth Token Helper

To obtain a Google OAuth refresh token for local development:

node get-token.cjs

This interactive script reads GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from your .env file, opens a browser for the OAuth consent flow, and writes the resulting refresh token back to .env.

---

License

MIT