🚀 Advanced SEO MCP Server

<div align="center">

Powering AI Agents with Advanced SEO Intelligence

</div>

📖 Overview

Advanced SEO MCP is a robust Model Context Protocol (MCP) server designed to equip AI agents with professional-grade SEO capabilities. It combines On-Page analysis, Technical Audits, Google PageSpeed Insights, and Ahrefs Data (via CapSolver) into a unified interface.

---

🚀 Installation

Option 1: One-Command Install (Recommended)

If you have uv installed, you can install this extension directly with Gemini CLI. uv handles all Python dependencies automatically.

gemini extensions install https://github.com/halilertekin/advanced-seo-mcp

Note: You will need to configure your API keys in the .env file inside the extension directory after installation.

Option 2: Manual Developer Setup

If you want to modify the code or don't use uv, follow these steps:

1. Clone the repository:

   git clone https://github.com/halilertekin/advanced-seo-mcp.git
   cd advanced-seo-mcp
   

2. Create virtual environment & Install:

   python3 -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   pip install -e .
   

3. Setup Configuration: Run the setup script to generate the local configuration:

   python setup_extension.py
   

4. Link to Gemini:

   ln -s $(pwd) ~/.gemini/extensions/advanced-seo-mcp
   

---

🔑 Configuration

This server requires API keys for full functionality.

1. Create a .env file in the project root (or rename .env.example):

   cp .env.example .env
   

2. Add your API keys:

   # Required for Ahrefs Tools (Backlinks, Keywords, Traffic)
   # Get key: https://dashboard.capsolver.com/
   CAPSOLVER_API_KEY="your_capsolver_key"
   
   # Required for PageSpeed Insights
   # Get key: https://developers.google.com/speed/docs/insights/v5/get-started
   GOOGLE_PSI_API_KEY="your_google_psi_key"
   

🛠️ Management & Execution

A handy skills.sh script is included for easy management of the MCP server.

Make the script executable:

chmod +x skills.sh

Available Commands:

• ./skills.sh install - Installs project dependencies using uv.
• ./skills.sh update - Compiles and upgrades dependencies.
• ./skills.sh audit - Runs a Python security audit (pip-audit).
• ./skills.sh run - Runs the advanced-seo MCP server.

---

📚 Tools Reference

Tool	Description
generate_audit_report	Best! Generates a full Markdown SEO report combining all metrics.
onpage_audit	Analyzes content structure, meta tags, and density.
analyze_page_speed	Google PageSpeed Insights analysis (Mobile/Desktop).
check_schema_markup	Validates JSON-LD Schema implementation.
check_broken_links_on_page	Scans page for broken (404) internal/external links.
compare_competitors	Compares Backlinks/Traffic/DR of 2 domains.
bulk_sitemap_audit	Scans sitemap and performs quick audit on multiple pages.
get_backlinks	Retrieves Domain Rating & Top Backlinks (Ahrefs Data).
keyword_ideas	Generates keyword ideas & questions (Ahrefs Data).

📝 License

MIT