npm package: @heyseo/mcp-server
Description: HeySeo MCP Server - Connect LLMs to your SEO data
Author: HeySeo
Latest version: 0.3.0

<div align="center">
  <img src="https://heyseo.app/img/logo.svg" alt="HeySeo Logo" width="200" />

  # 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**
</div>

## Quick Start

### 1. Get your API Key

1. Sign up at [heyseo.app](https://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:

<details>
<summary><strong>Claude Desktop</strong></summary>

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

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

<details>
<summary><strong>Claude Code (CLI)</strong></summary>

Edit `~/.claude/settings.json`:

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

<details>
<summary><strong>Cursor</strong></summary>

Edit your Cursor MCP settings:

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

<details>
<summary><strong>Windsurf</strong></summary>

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

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

<details>
<summary><strong>ChatGPT Desktop</strong></summary>

ChatGPT Desktop supports MCP servers. Add to your settings:

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

<details>
<summary><strong>Local Development</strong></summary>

If you're running from source:

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

> **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.

---

## 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](https://heyseo.app)
- Email: hello@heyseo.app