HeySeo MCP Server

Connect your LLM to your SEO data. Query Google Search Console, Google Analytics 4, PageSpeed Insights, SERP data, indexing health, AI insights, and more — directly from Claude, ChatGPT, Cursor, or any MCP-compatible client.

35 tools | 10 resources | 12 prompts

Quick Start

1. Get your API Key

1. Sign up at heyseo.app
2. Connect your Google Search Console and/or GA4 properties
3. Go to Settings > API and generate an API key

2. Configure your MCP Client

Choose your client below and add the configuration:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "heyseo": {
      "command": "npx",
      "args": ["-y", "@heyseo/mcp-server"],
      "env": {
        "HEYSEO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "heyseo": {
      "command": "npx",
      "args": ["-y", "@heyseo/mcp-server"],
      "env": {
        "HEYSEO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Edit your Cursor MCP settings:

{
  "mcpServers": {
    "heyseo": {
      "command": "npx",
      "args": ["-y", "@heyseo/mcp-server"],
      "env": {
        "HEYSEO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "heyseo": {
      "command": "npx",
      "args": ["-y", "@heyseo/mcp-server"],
      "env": {
        "HEYSEO_API_KEY": "your_api_key_here"
      }
    }
  }
}

ChatGPT Desktop supports MCP servers. Add to your settings:

{
  "mcpServers": {
    "heyseo": {
      "command": "npx",
      "args": ["-y", "@heyseo/mcp-server"],
      "env": {
        "HEYSEO_API_KEY": "your_api_key_here"
      }
    }
  }
}

If you're running from source:

{
  "mcpServers": {
    "heyseo": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "HEYSEO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Note: The -y flag is required for npx to skip installation prompts, which would otherwise cause the server to hang.

3. Restart your client

Restart Claude Desktop, Cursor, or your MCP client to load the new server.

Available Tools

Site Management

Select a site before running SEO operations. The MCP server requires explicit site selection to ensure data isolation and prevent accidental cross-site operations.

| Tool | Description | |------|-------------| | heyseo_list_sites | List all available sites and their connection status (GSC/GA4) | | heyseo_select_site | Select a specific site for all subsequent operations | | heyseo_get_current_site | Get information about the currently selected site |

Google Search Console

| Tool | Description | |------|-------------| | heyseo_query_gsc | Query Google Search Console with custom dimensions and filters | | heyseo_top_keywords | Get top performing keywords for a site | | heyseo_top_pages | Get top performing pages for a site | | heyseo_ranking_history | Track keyword position changes over time (7-90 days) |

Google Analytics 4

| Tool | Description | |------|-------------| | heyseo_query_ga4 | Query Google Analytics 4 data | | heyseo_landing_pages | Get landing page performance with engagement metrics | | heyseo_traffic_sources | Analyze traffic sources and channels |

PageSpeed & Performance

| Tool | Description | |------|-------------| | heyseo_pagespeed | Run PageSpeed Insights analysis with Core Web Vitals | | heyseo_pagespeed_bulk | Analyze multiple pages at once |

Comparison & Opportunities

| Tool | Description | |------|-------------| | heyseo_compare_periods | Compare SEO metrics between two time periods | | heyseo_week_over_week | Quick week-over-week comparison | | heyseo_find_opportunities | Discover SEO optimization opportunities |

Task Management

| Tool | Description | |------|-------------| | heyseo_create_task | Create a single SEO task in HeySeo Kanban | | heyseo_list_tasks | List all tasks for a site with optional filters | | heyseo_get_task | Get detailed information about a specific task | | heyseo_update_task | Update task title, description, status, priority, or category | | heyseo_delete_task | Delete a task from the Kanban board | | heyseo_bulk_create_tasks | Create multiple tasks at once (up to 10) | | heyseo_bulk_update_tasks | Update multiple tasks at once (up to 10) |

Reports

| Tool | Description | |------|-------------| | heyseo_list_reports | List AI-generated SEO reports (weekly/monthly) | | heyseo_get_report | Get full report details including metrics and AI analysis |

Indexing Health

| Tool | Description | |------|-------------| | heyseo_indexing_status | Get indexing health summary (indexed/not-indexed counts, health score) | | heyseo_indexing_pages | List pages with their indexing verdict and coverage state | | heyseo_submit_for_indexing | Submit a page to Google's Indexing API for faster indexing |

SEO Memory

| Tool | Description | |------|-------------| | heyseo_get_memory | Get full SEO memory context (strategy, goals, learnings, health trend) | | heyseo_update_strategy | Update SEO strategy summary, create goals, or update goal progress | | heyseo_record_action | Record an SEO action taken on the site with hypothesis and metrics to track | | heyseo_add_learning | Add a key fact or success pattern to the site's learning memory |

AI Insights

| Tool | Description | |------|-------------| | heyseo_get_insights | Get AI-generated insights (anomalies, opportunities, alerts, trends, milestones) |

On-Page Audit

| Tool | Description | |------|-------------| | heyseo_onpage_audit | Run a full on-page SEO audit on any URL (score, meta tags, headings, links, images, issues) |

SERP Analysis

| Tool | Description | |------|-------------| | heyseo_serp_search | Search Google SERP for a keyword with organic results, featured snippets, and PAA |

Sitemaps

| Tool | Description | |------|-------------| | heyseo_list_sitemaps | List sitemaps registered in Google Search Console with status and errors |

Resources

Access your SEO data as readable resources:

| URI | Description | |-----|-------------| | heyseo://sites | List all connected sites | | heyseo://sites/{id} | Site details | | heyseo://sites/{id}/overview | Current metrics overview (last 28 days) | | heyseo://sites/{id}/keywords | Top 50 keywords | | heyseo://sites/{id}/pages | Top 50 pages | | heyseo://sites/{id}/reports | Recent AI-generated SEO reports | | heyseo://sites/{id}/indexing | Indexing health summary | | heyseo://sites/{id}/insights | AI-generated insights | | heyseo://sites/{id}/memory | SEO memory context (strategy, goals, learnings) | | heyseo://sites/{id}/sitemaps | GSC sitemaps |

Prompts

Pre-built prompts for common SEO tasks:

| Prompt | Description | |--------|-------------| | seo_audit | Comprehensive SEO audit | | weekly_report | Weekly performance report | | keyword_research | Keyword analysis and opportunities | | content_optimization | Page optimization recommendations | | technical_health_check | Core Web Vitals and performance | | traffic_analysis | Traffic patterns and sources | | quick_wins | Low-effort, high-impact opportunities | | ranking_changes | Recent ranking changes analysis | | task_review | Review and prioritize SEO tasks | | indexing_audit | Indexing health audit with fix recommendations | | strategy_review | Review and update SEO strategy based on memory | | insights_briefing | Summarize recent insights and suggest actions |

Usage Examples

Site Selection (Start here!)

Before performing any SEO operations, you must select a site:

List available sites:

"Show me all my connected sites"

Select a site:

"Select the site with ID: abc123def456"

Check current site:

"What site am I currently working with?"

Performance Analysis

"What are my top 10 keywords this month?"

"How did we do this week vs last week?"

"Check the page speed for our homepage"

"How has my ranking for 'best seo tools' changed over the last 30 days?"

Audits & Opportunities

"Run an SEO audit on my site"

"Find quick win SEO opportunities"

"Run an on-page audit on https://example.com/blog/post"

"Search Google for 'best project management tools' and show me the SERP"

Indexing Health

"What's my indexing health status?"

"Show me pages that aren't indexed"

"Submit my /new-landing-page for indexing"

Reports & Insights

"Show me my latest SEO reports"

"What AI insights do you have for my site?"

"Give me an insights briefing"

Strategy & Memory

"What's our current SEO strategy?"

"Update the strategy summary to focus on technical SEO improvements"

"Create a goal to increase organic clicks by 20% by Q3"

"Record that we optimized all meta descriptions today"

"Add a learning: long-form guides rank better for informational queries"

Task Management

"Review my SEO tasks and help me prioritize them"

"Create tasks for the top 5 issues you found in the audit"

"Mark all the technical tasks as done"

Sitemaps

"List my sitemaps from Google Search Console"

API Key Scopes

When creating an API key, you can restrict access to specific features:

| Scope | Description | |-------|-------------| | sites:read | Read site information | | gsc:read | Read Google Search Console data | | ga4:read | Read Google Analytics 4 data | | pagespeed:read | Run PageSpeed analyses | | tasks:read | Read tasks | | tasks:write | Create, update, delete tasks | | reports:read | Read AI-generated reports | | indexing:read | Read indexing status and pages | | indexing:write | Submit pages for indexing | | memory:read | Read SEO memory context | | memory:write | Update strategy, goals, actions, learnings | | insights:read | Read AI-generated insights | | onpage:read | Run on-page audits | | serp:read | Search Google SERP | | sitemaps:read | Read GSC sitemaps |

Use all scope for full access.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | HEYSEO_API_KEY | Yes | - | Your HeySeo API key | | HEYSEO_API_URL | No | https://www.heyseo.app | Custom API URL |

Rate Limits

• 100 requests per minute
• 10,000 requests per day

License

MIT

Support

• Website: heyseo.app
• Email: [email protected]