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.

72 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 | | heyseo_update_site | Update site settings (name, URL) | | heyseo_delete_site | Delete a site from your account | | heyseo_sync_analytics | Trigger an analytics data sync for a 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 | | heyseo_pagespeed_history | Get PageSpeed analysis history for a site |

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_move_task | Move or reorder a task on 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 | | heyseo_generate_report | Generate a new SEO report on demand | | heyseo_delete_report | Delete a report | | heyseo_report_settings | Get report schedule settings for a site | | heyseo_update_report_settings | Update report schedule (day, time, frequency) | | heyseo_send_test_report | Send a test report email to verify setup |

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 | | heyseo_indexing_check | Trigger an indexing check for all monitored pages | | heyseo_indexing_history | Get indexing check history over time | | heyseo_indexing_settings | Get indexing monitoring settings | | heyseo_update_indexing_settings | Update indexing monitoring settings | | heyseo_indexing_submissions | Get indexing submission history | | heyseo_remove_indexing_page | Remove a page from indexing monitoring |

SEO Memory

| Tool | Description | |------|-------------| | heyseo_get_memory | Get full SEO memory context (strategy, goals, learnings, health trend) | | heyseo_update_strategy | Update SEO strategy summary | | heyseo_record_action | Record an SEO action with hypothesis and metrics to track | | heyseo_add_learning | Add a key fact or success pattern to site memory | | heyseo_delete_goal | Delete a goal | | heyseo_memory_snapshots | Get performance snapshots over time | | heyseo_generate_snapshot | Generate a new performance snapshot | | heyseo_queue_action | Queue an action for future implementation | | heyseo_update_queued_action | Update a queued action's status or priority |

AI Insights

| Tool | Description | |------|-------------| | heyseo_get_insights | Get AI-generated insights (anomalies, opportunities, alerts, trends) | | heyseo_generate_insights | Generate new AI insights on demand |

AI Knowledge

| Tool | Description | |------|-------------| | heyseo_get_knowledge | Get the AI knowledge base for a site | | heyseo_update_knowledge | Update AI knowledge (business context, competitors, goals) |

AI Chat

| Tool | Description | |------|-------------| | heyseo_chat | Send a message to the AI assistant about your SEO data |

Conversations

| Tool | Description | |------|-------------| | heyseo_list_conversations | List AI chat conversations | | heyseo_get_conversation | Get a conversation with all messages | | heyseo_create_conversation | Create a new conversation | | heyseo_delete_conversation | Delete a conversation |

On-Page Audit

| Tool | Description | |------|-------------| | heyseo_onpage_audit | Run a full on-page SEO audit on any URL | | heyseo_onpage_history | Get on-page audit history for a site |

SERP Analysis

| Tool | Description | |------|-------------| | heyseo_serp_search | Search Google SERP for a keyword with organic results, featured snippets, and PAA | | heyseo_serp_history | Get SERP search history | | heyseo_serp_batch | Batch SERP preview for multiple keywords at once |

Sitemaps

| Tool | Description | |------|-------------| | heyseo_list_sitemaps | List sitemaps registered in Google Search Console | | heyseo_submit_sitemap | Submit a sitemap to Google Search Console | | heyseo_delete_sitemap | Delete a sitemap from Google Search Console |

DataForSEO

| Tool | Description | |------|-------------| | heyseo_keyword_volume | Get keyword search volume data for one or more keywords |

Notifications

| Tool | Description | |------|-------------| | heyseo_notification_settings | Get notification settings | | heyseo_update_notification_settings | Update notification preferences |

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"

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"

"Run an indexing check on all monitored pages"

"Show me the indexing submission history"

Reports & Insights

"Show me my latest SEO reports"

"Generate a new weekly report"

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

"Generate fresh insights for my site"

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"

"Take a performance snapshot"

"Queue an action to rewrite our FAQ page"

AI Chat & Knowledge

"Chat with the AI about my site's SEO performance"

"Show me the AI knowledge base for this site"

"Update the knowledge base with our business context"

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"

"Move the title tag task to in-progress"

Keyword Research

"Get search volume for 'seo tools', 'seo software', 'seo platform'"

Sitemaps

"List my sitemaps from Google Search Console"

"Submit a new sitemap at /sitemap.xml"

API Key Scopes

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

| Scope | Description | |-------|-------------| | sites:read | Read site information | | sites:write | Update or delete sites | | gsc:read | Read Google Search Console data | | ga4:read | Read Google Analytics 4 data | | pagespeed:read | Run PageSpeed analyses and view history | | tasks:read | Read tasks | | tasks:write | Create, update, delete, move tasks | | reports:read | Read AI-generated reports and settings | | reports:write | Generate, delete reports and update settings | | indexing:read | Read indexing status, pages, history, settings | | indexing:write | Submit for indexing, run checks, update settings, remove pages | | memory:read | Read SEO memory, snapshots | | memory:write | Update strategy, goals, actions, learnings, snapshots | | insights:read | Read AI-generated insights | | insights:write | Generate new insights | | knowledge:read | Read AI knowledge base | | knowledge:write | Update AI knowledge | | onpage:read | Run on-page audits and view history | | serp:read | Search Google SERP and view history | | sitemaps:read | Read GSC sitemaps | | sitemaps:write | Submit or delete GSC sitemaps | | chat:write | Send messages to AI assistant | | conversations:read | Read conversations | | conversations:write | Create or delete conversations | | notifications:read | Read notification settings | | notifications:write | Update notification settings | | dataforseo:read | Access keyword volume data |

Use all scope for full access.

REST API Reference

If you're calling HeySeo directly via HTTP (not through the MCP server), use these endpoints.

Base URL: https://my.heyseo.app

Authentication: All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate limit: 100 requests/minute

Sites

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | GET | /api/mcp/sites | sites:read | List all sites | | GET | /api/mcp/sites/:id | sites:read | Get site details | | PATCH | /api/mcp/sites/:id | sites:write | Update site (body: { displayName }) | | DELETE | /api/mcp/sites/:id | sites:write | Delete a site |

Google Search Console

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | POST | /api/mcp/sites/:id/gsc | gsc:read | Query GSC analytics | | POST | /api/mcp/sites/:id/analytics | gsc:read | Query GSC analytics (with cache) | | GET | /api/mcp/sites/:id/opportunities | gsc:read | Find SEO opportunities |

GSC query body:

{
  "startDate": "2026-01-01",
  "endDate": "2026-03-14",
  "dimensions": ["query", "page", "country", "device", "date"],
  "rowLimit": 1000,
  "startRow": 0,
  "filters": [
    { "dimension": "query", "operator": "contains", "expression": "seo" }
  ]
}

Google Analytics 4

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | POST | /api/mcp/sites/:id/ga4 | ga4:read | Query GA4 data |

GA4 query body:

{
  "startDate": "2026-01-01",
  "endDate": "2026-03-14",
  "dimensions": ["date", "landingPage", "pagePath", "sessionSource", "sessionMedium", "deviceCategory", "country", "city"],
  "metrics": ["sessions", "activeUsers", "newUsers", "engagementRate", "bounceRate", "averageSessionDuration", "screenPageViews", "conversions", "eventCount"],
  "limit": 1000
}

PageSpeed

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | POST | /api/mcp/pagespeed | pagespeed:read | Run PageSpeed analysis (body: { url, strategy?: "mobile"\|"desktop" }) | | GET | /api/mcp/pagespeed/history?siteId=X | pagespeed:read | Get PageSpeed history |

SERP Analysis

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | POST | /api/mcp/serp | serp:read | Search Google SERP (body: { query, siteId?, country?, language?, numResults? }) | | GET | /api/mcp/serp/history | serp:read | Get SERP search history | | POST | /api/mcp/serp/batch-preview | serp:read | Batch SERP for up to 5 keywords (body: { siteId, queries: [] }) |

On-Page Audit

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | POST | /api/mcp/onpage | onpage:read | Run on-page SEO audit (body: { url, siteId? }) | | GET | /api/mcp/onpage/history?siteId=X | onpage:read | Get audit history |

AI Chat

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | POST | /api/mcp/chat | chat:write | Send message to AI (body: { message, siteId, conversationId?, conversationHistory? }) |

Conversations

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | GET | /api/mcp/conversations?siteId=X | conversations:read | List conversations | | POST | /api/mcp/conversations | conversations:write | Create conversation (body: { siteId, title? }) | | GET | /api/mcp/conversations/:id?siteId=X | conversations:read | Get conversation with messages | | DELETE | /api/mcp/conversations/:id | conversations:write | Delete conversation |

Reports

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | GET | /api/mcp/reports?siteId=X&type=weekly&limit=20 | reports:read | List reports | | POST | /api/mcp/reports | reports:write | Generate report (body: { siteId, type: "weekly"\|"monthly", template? }) | | GET | /api/mcp/reports/:id | reports:read | Get full report | | DELETE | /api/mcp/reports/:id | reports:write | Delete report | | POST | /api/mcp/reports/send-test | reports:write | Send test report email (body: { siteId, type }) | | GET | /api/mcp/reports/settings/:siteId | reports:read | Get report settings | | PATCH | /api/mcp/reports/settings/:siteId | reports:write | Update report settings |

Tasks

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | POST | /api/mcp/tasks | tasks:write | Create task (body: { siteId, title, description?, priority?, category? }) | | POST | /api/mcp/tasks/bulk | tasks:write | Create up to 10 tasks | | PATCH | /api/mcp/tasks/bulk | tasks:write | Update up to 10 tasks (body: { taskIds, updates }) | | PATCH | /api/mcp/tasks/:id/move | tasks:write | Move task (body: { columnId, order }) |

Indexing

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | GET | /api/mcp/indexing/:siteId/status | indexing:read | Indexing health summary | | GET | /api/mcp/indexing/:siteId/pages?status=all | indexing:read | List monitored pages | | POST | /api/mcp/indexing/:siteId/submit | indexing:write | Submit page for indexing (body: { pageId }) | | POST | /api/mcp/indexing/:siteId/check | indexing:write | Trigger indexing check | | GET | /api/mcp/indexing/:siteId/history?days=30 | indexing:read | Indexing check history | | GET | /api/mcp/indexing/:siteId/submissions | indexing:read | Submission history | | DELETE | /api/mcp/indexing/:siteId/pages/:pageId | indexing:write | Remove page from monitoring | | GET | /api/mcp/indexing/:siteId/settings | indexing:read | Get indexing settings | | PATCH | /api/mcp/indexing/:siteId/settings | indexing:write | Update indexing settings |

SEO Memory

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | GET | /api/mcp/memory/:siteId/context | memory:read | Get full SEO memory context | | PATCH | /api/mcp/memory/:siteId/strategy | memory:write | Update strategy (body: { strategySummary }) | | POST | /api/mcp/memory/:siteId/goals | memory:write | Create goal (body: { type, description, targetValue, targetDate? }) | | PATCH | /api/mcp/memory/:siteId/goals/:goalId | memory:write | Update goal | | DELETE | /api/mcp/memory/:siteId/goals/:goalId | memory:write | Delete goal | | POST | /api/mcp/memory/:siteId/learnings | memory:write | Add learning (body: { type: "fact"\|"pattern", fact?, pattern? }) | | POST | /api/mcp/memory/:siteId/actions | memory:write | Record action with hypothesis | | POST | /api/mcp/memory/:siteId/actions/:id/outcome | memory:write | Record action outcome | | POST | /api/mcp/memory/:siteId/action-queue | memory:write | Queue action | | PATCH | /api/mcp/memory/:siteId/action-queue/:id | memory:write | Update queued action | | GET | /api/mcp/memory/:siteId/snapshots | memory:read | List snapshots | | POST | /api/mcp/memory/:siteId/snapshots/generate | memory:write | Generate snapshot |

AI Insights & Knowledge

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | GET | /api/mcp/insights/:siteId | insights:read | Get AI insights | | POST | /api/mcp/insights/:siteId/generate | insights:write | Generate new insights | | GET | /api/mcp/knowledge/:siteId | knowledge:read | Get AI knowledge base | | PATCH | /api/mcp/knowledge/:siteId | knowledge:write | Update AI knowledge |

Sitemaps

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | GET | /api/mcp/sitemaps/:siteId | sitemaps:read | List GSC sitemaps | | PUT | /api/mcp/sitemaps/:siteId | sitemaps:write | Submit sitemap (body: { feedpath }) | | DELETE | /api/mcp/sitemaps/:siteId?feedpath=X | sitemaps:write | Delete sitemap |

Notifications

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | GET | /api/mcp/notifications/settings | notifications:read | Get notification settings | | PATCH | /api/mcp/notifications/settings | notifications:write | Update notification settings |

DataForSEO

| Method | Endpoint | Scope | Description | |--------|----------|-------|-------------| | POST | /api/mcp/dataforseo/keywords/volume | dataforseo:read | Get keyword search volume (body: { keywords: [], locationCode?, languageCode? }) |

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | HEYSEO_API_KEY | Yes | - | Your HeySeo API key | | HEYSEO_API_URL | No | https://my.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]