seo-mcp-server

🔍 SEO MCP Server

Powerful SEO Analysis & Validation for AI Assistants

Live Demo | Documentation | Quick Start | Contributing

---

📖 About

A comprehensive SEO validation and analysis server built on the Model Context Protocol (MCP). This server empowers AI assistants like Claude with professional-grade SEO tools to validate, analyze, and optimize websites for search engines — delivering actionable, prioritized recommendations in real-time.

Built on Cloudflare Workers for blazing-fast global edge deployment with integrated caching, rate limiting, and production-ready error tracking via Sentry.

🌟 Why This Server?

• 🚀 Edge-Native Performance — Deployed globally on Cloudflare's edge network for <50ms response times
• 🤖 AI-First Design — Structured outputs optimized for LLM consumption and analysis
• 🔒 Production-Ready — Built-in SSRF protection, rate limiting, caching, and error tracking
• 📊 Comprehensive Analysis — 6 specialized tools covering all aspects of modern SEO
• 🎯 Framework-Aware — Auto-detects and provides tailored advice for Next.js, Nuxt, React, Vue, and more
• 🆓 Open Source — MIT licensed, community-driven, transparent

✨ Features

🛠️ Tools (6 Specialized Validators)

📚 Resources (6 Best Practice Guides)

Built-in knowledge base accessible via MCP Resources:

Resource	URI	Content
Meta Tags Guide	seo://best-practices/meta-tags	Complete guide to optimizing title, description, OG tags, Twitter Cards
Structured Data Guide	seo://best-practices/structured-data	Schema.org implementation, JSON-LD syntax, rich snippets
Technical SEO Guide	seo://best-practices/technical-seo	robots.txt, sitemaps, canonicals, headers, international SEO
Core Web Vitals Guide	seo://best-practices/performance	LCP, INP, CLS optimization strategies
Accessibility Guide	seo://best-practices/accessibility	WCAG 2.1 compliance, inclusive design principles
E-E-A-T Guide	seo://best-practices/eat-guide	Experience, Expertise, Authoritativeness, Trustworthiness for content

🎯 Prompts (3 Ready-to-Use Audit Templates)

Pre-configured audit workflows for common use cases:

Prompt	Use Case	What It Does
full_seo_audit	Complete site analysis	Runs all validators, provides comprehensive report with prioritized action items
quick_seo_check	Fast health check	Meta tags + structured data + basic technical checks (~30 seconds)
technical_seo_audit	Infrastructure focus	Deep dive into robots.txt, sitemaps, canonicals, headers, redirects

---

🚀 Quick Start

Option 1: Use the Live Server (Fastest)

No setup required! Use the public deployment:

{
  "mcpServers": {
    "seo-validation": {
      "url": "https://seo-mcp-server.oday-bakkour.com/mcp"
    }
  }
}

Add this to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.) and start auditing websites immediately.

Option 2: Deploy Your Own Instance

Want your own deployment? Follow these steps:

Prerequisites

• Node.js v18 or higher
• Wrangler CLI (Cloudflare Workers toolkit)
• Cloudflare account (free tier works perfectly)
• Git

1. Clone & Install

git clone https://github.com/Docker-Hunterpedia/seo-mcp-server.git
cd seo-mcp-server
npm install

2. Cloudflare Setup

# Login to Cloudflare
wrangler login

# Create KV namespaces for caching and rate limiting
npx wrangler kv:namespace create VALIDATION_CACHE
npx wrangler kv:namespace create RATE_LIMITS

Update wrangler.toml with the returned namespace IDs:

[[kv_namespaces]]
binding = "VALIDATION_CACHE"
id = "your-cache-namespace-id"

[[kv_namespaces]]
binding = "RATE_LIMITS"
id = "your-rate-limit-namespace-id"

Also update your account_id in wrangler.toml.

3. Configure Secrets

# Required: Sentry DSN for error tracking (get free account at sentry.io)
npx wrangler secret put SENTRY_DSN

# Optional but recommended: Google PageSpeed Insights API key
# Without it, performance checks work but with lower rate limits
# Get a free key at https://developers.google.com/speed/docs/insights/v5/get-started
npx wrangler secret put PAGESPEED_API_KEY

4. Deploy

# Development deployment
npm run deploy:staging

# Production deployment
npm run deploy:production

# View live logs
npx wrangler tail --env production

Your server will be available at https://your-worker.your-subdomain.workers.dev/mcp

---

💻 Development

Local Development

npm run dev          # Start local dev server at http://localhost:8787
npm test             # Run all tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Generate coverage report
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint code linting
npm run format       # Format code with Prettier

Project Structure

src/
├── index.ts                    # Cloudflare Workers entry point
├── server.ts                   # MCP server setup & tool registration
├── tools/                      # SEO validation tools (core functionality)
│   ├── meta-tags.ts           #   → Meta tag validation
│   ├── structured-data.ts     #   → JSON-LD & Schema.org validation
│   ├── technical-seo.ts       #   → Technical SEO audit
│   ├── performance.ts         #   → Core Web Vitals (PageSpeed)
│   ├── accessibility.ts       #   → WCAG compliance audit
│   ├── full-audit.ts          #   → Comprehensive audit aggregator
│   └── content.ts             #   → Content quality analysis
├── lib/                       # Shared utilities & infrastructure
│   ├── cache.ts               #   → KV-based result caching
│   ├── errors.ts              #   → Error types & MCP formatting
│   ├── fetch.ts               #   → Safe fetch with SSRF protection
│   ├── rate-limiter.ts        #   → IP-based rate limiting
│   ├── security.ts            #   → URL validation & security checks
│   └── validators/            #   → HTML parsing & analysis
│       ├── framework-detector.ts  # Framework detection logic
│       └── html.ts            #   HTML parsing utilities
├── middleware/
│   └── sentry.ts              # Error tracking & performance monitoring
├── resources/                 # MCP Resources (best practice guides)
│   ├── meta-tags-guide.ts
│   ├── structured-data-guide.ts
│   ├── technical-seo-guide.ts
│   ├── core-web-vitals-guide.ts
│   ├── accessibility-guide.ts
│   ├── eeat-guide.ts
│   ├── nextjs-seo-guide.ts
│   ├── nuxt-seo-guide.ts
│   └── mobile-first-guide.ts
├── prompts/                   # MCP Prompts (audit templates)
│   ├── full-audit-prompt.ts
│   ├── quick-check-prompt.ts
│   └── framework-audit-prompt.ts
└── types/                     # TypeScript definitions
    ├── env.ts                 # Environment variables
    ├── seo.types.ts          # SEO-specific types
    └── validation.types.ts   # Validation schemas

tests/
├── fixtures/                  # Test HTML samples
├── unit/                      # Unit tests for individual modules
└── integration/               # Full audit integration tests

Key Technical Decisions

---

🤖 Using with MCP Clients

Configuration

Add to your MCP client's configuration file:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "seo-validation": {
      "url": "https://seo-mcp-server.oday-bakkour.com/mcp"
    }
  }
}

Cursor/Windsurf (.cursorrules or settings):

{
  "mcpServers": {
    "seo-validation": {
      "url": "https://seo-mcp-server.oday-bakkour.com/mcp"
    }
  }
}

Example Prompts

Once configured, ask your AI assistant:

• "Run a full SEO audit on https://example.com"
  → Comprehensive analysis with prioritized recommendations

• "Check the meta tags on https://mysite.com"
  → Title, description, Open Graph, Twitter Cards validation

• "Validate the structured data on this page"
  → JSON-LD syntax, Schema.org compliance, rich snippet eligibility

• "How are the Core Web Vitals for https://example.com on mobile?"
  → LCP, INP, CLS, TTFB metrics with optimization tips

• "Check the accessibility of https://mysite.com for WCAG AA compliance"
  → Alt text, headings, ARIA labels, color contrast auditing

• "What technical SEO issues does https://example.com have?"
  → robots.txt, sitemap, canonicals, headers, redirects analysis

The AI assistant will use the appropriate tools and provide detailed, actionable insights.

---

📊 API Response Format

All tools return structured JSON optimized for LLM consumption:

{
  "status": "success",
  "url": "https://example.com",
  "timestamp": "2026-02-14T10:30:00Z",
  "framework": "Next.js",
  "issues": [
    {
      "severity": "critical",
      "category": "meta-tags",
      "issue": "Missing meta description",
      "location": "<head>",
      "recommendation": "Add a compelling 150-160 character meta description",
      "impact": "Meta descriptions influence CTR in search results"
    }
  ],
  "summary": {
    "totalIssues": 12,
    "critical": 2,
    "high": 4,
    "medium": 5,
    "low": 1,
    "score": 68
  },
  "nextSteps": [
    "Fix critical issues first: missing meta description, broken canonical tag",
    "Consider implementing Schema.org structured data for better rich snippets"
  ]
}

---

🏗️ Architecture

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client                                │
│            (Claude Desktop, Cursor, Windsurf)                    │
└────────────────────────┬────────────────────────────────────────┘
                         │ MCP Protocol (Server-Sent Events)
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                  Cloudflare Workers (Edge)                       │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ Rate Limiter │  │ SSRF Guard   │  │ Sentry       │          │
│  │ (IP-based)   │  │ (Security)   │  │ (Monitoring) │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         └─────────────────┴──────────────────┘                  │
│                         │                                        │
│                         ▼                                        │
│              ┌────────────────────┐                              │
│              │   MCP Server Core  │                              │
│              │  (Tool Registry)   │                              │
│              └─────────┬──────────┘                              │
│                        │                                         │
│        ┌───────────────┼───────────────┬───────────┐            │
│        ▼               ▼               ▼           ▼            │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐  ┌──────────┐      │
│  │ Meta    │    │ Struct. │    │ Tech.   │  │ Perf.    │      │
│  │ Tags    │    │ Data    │    │ SEO     │  │ (CWV)    │      │
│  └────┬────┘    └────┬────┘    └────┬────┘  └─────┬────┘      │
│       │              │              │              │            │
│       └──────────────┴──────────────┴──────────────┘            │
│                         │                                        │
│                         ▼                                        │
│              ┌────────────────────┐                              │
│              │   KV Cache Layer   │                              │
│              │   (1 hour TTL)     │                              │
│              └────────────────────┘                              │
└────────────────────────┬────────────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
┌───────────────┐  ┌──────────────┐  ┌──────────────┐
│  Target Site  │  │  Google PSI  │  │   Sentry     │
│  (crawling)   │  │  API         │  │   (errors)   │
└───────────────┘  └──────────────┘  └──────────────┘

Data Flow

1. MCP Client sends tool invocation request via SSE transport
2. Rate Limiter checks IP-based limits (100 req/hour)
3. Security Layer validates URLs, prevents SSRF attacks
4. Cache Layer checks for existing results (1hr TTL)
5. Tool Executor runs validation logic (fetch, parse, analyze)
6. Response Formatter structures output for LLM consumption
7. Sentry logs errors and performance metrics
8. MCP Protocol streams results back to client

---

🤝 Contributing

Contributions are welcome and appreciated! Whether you're fixing bugs, adding features, improving documentation, or suggesting enhancements, your help makes this project better.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test thoroughly:

   npm test               # Run all tests
   npm run typecheck      # Type checking
   npm run lint           # Linting
   

5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Contribution Ideas

• 🐛 Bug fixes — Found an issue? Please report it or submit a fix!
• ✨ New validators — Additional SEO checks (e.g., image optimization, internal linking)
• 📚 Documentation — Improve guides, add examples, fix typos
• 🧪 Tests — Increase test coverage, add edge cases
• 🎨 Framework support — Add detection for more frameworks
• 🌍 Internationalization — Multi-language SEO validation
• ⚡ Performance — Optimize parsing, reduce response times

Development Guidelines

• Code Style — Use Prettier (run npm run format)
• Type Safety — Leverage TypeScript fully, avoid any
• Testing — Write tests for new features (Vitest)
• Documentation — Update README and inline docs
• Commits — Use clear, descriptive commit messages
• Pull Requests — Include description, context, and screenshots if UI-related

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

MIT License

Copyright (c) 2026 Oday Bakkour

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

TL;DR: You can use, modify, and distribute this software freely. Just keep the copyright notice.

---

🔒 Security

Security is a top priority. This server includes multiple layers of protection:

• ✅ SSRF Protection — Blocks requests to private IPs, metadata endpoints, localhost
• ✅ Rate Limiting — IP-based throttling prevents abuse (100 req/hour)
• ✅ Input Validation — All inputs validated with Zod schemas
• ✅ URL Limits — Maximum 2048 characters to prevent abuse
• ✅ Safe Fetch — Timeout limits, redirect following with re-validation
• ✅ No Secrets in Code — API keys stored as Cloudflare Worker secrets

Reporting Vulnerabilities

Found a security issue? Please report responsibly:

• 🚫 Do NOT open a public GitHub issue for security vulnerabilities
• ✉️ Email: contact@oday-bakkour.com
• 🔒 Or use GitHub's private vulnerability reporting

We aim to acknowledge reports within 48 hours and provide fixes within 7 days for critical issues.

See SECURITY.md for full details.

---

👤 Author & Maintainer

Oday Bakkour

Developer, SEO Expert, and Open Source Contributor

---

🙏 Acknowledgments

• Model Context Protocol — Making AI assistants extensible
• Cloudflare Workers — Edge computing platform
• Google PageSpeed Insights — Core Web Vitals data
• Sentry — Error tracking and performance monitoring
• All contributors — Thank you for helping improve this project!

---

📞 Support & Questions

• 📖 Documentation: You're reading it! Check the sections above
• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• ✉️ Email: contact@oday-bakkour.com
• 🌐 Website: oday-bakkour.com
• 🐦 Twitter/X: @Oday_Hunter
• 💼 LinkedIn: Oday Bakkour
• 🐙 GitHub: @Docker-Hunterpedia

---

📈 Roadmap

Future enhancements planned:

• Content Quality Scoring — Readability, keyword density, content depth analysis
• Image Optimization — Alt text, file size, format, lazy loading checks
• Internal Linking — Link structure, anchor text, orphan page detection
• Mobile Usability — Touch target sizes, viewport issues, mobile-specific errors
• Multilingual SEO — hreflang validation, international targeting
• Competitive Analysis — Compare multiple URLs side-by-side
• Historical Tracking — Track SEO metrics over time
• Custom Rules — User-defined validation rules and thresholds
• Webhooks — Automated audits triggered by deployments
• Browser Rendering — JavaScript-heavy sites with Puppeteer/Playwright

Suggestions? Open a feature request!

---

⭐ If this project helps you, consider starring it on GitHub!

Made with ❤️ by Oday Bakkour

Live Demo • Documentation • GitHub • Report Bug