@heyseo/mcp-server

# HeySeo MCP Server

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

Quick Start

$3

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

$3

Choose your client below and add the configuration:

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

$3

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

---

Available Tools

$3

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 |

$3

| 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) |

$3

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

$3

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

$3

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

$3

| 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) |

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 |
| heyseo://sites/{id}/keywords | Top 50 keywords |
| heyseo://sites/{id}/pages | Top 50 pages |

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 for a site |

---

Usage Examples

$3

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"
>
> Or ask Claude to list sites and select one for you

Check current site:
> "What site am I currently working with?"

$3

Once a site is selected, you can perform SEO operations:

Get top keywords:
> "What are my top 10 keywords this month?"

Run an SEO audit:
> "Run an SEO audit on my site"

Compare performance:
> "How did we do this week vs last week?"

Analyze page speed:
> "Check the page speed for our homepage"

Find opportunities:
> "Find quick win SEO opportunities"

Track keyword ranking history:
> "How has my ranking for 'best seo tools' changed over the last 30 days?"

Review and prioritize tasks:
> "Review my SEO tasks and help me prioritize them"

Create tasks from audit findings:
> "Create tasks for the top 5 issues you found in the audit"

Bulk update task status:
> "Mark all the technical tasks as done"

---

Site Selection Workflow

The HeySeo MCP server uses explicit site selection to prevent data isolation issues:

$3

1. Initialize: User starts a conversation with Claude
2. List Sites: User asks to see available sites
`
→ heyseo_list_sites
← Returns all available sites with IDs and connection status
`
3. Select Site: User chooses which site to work with
`
→ heyseo_select_site { siteId: "your-site-id" }
← Confirms selection and shows site details
`
4. Verify Selection: (Optional) User confirms the current site
`
→ heyseo_get_current_site
← Returns details of the selected site
`
5. Perform Operations: All subsequent SEO operations use the selected site
`
→ heyseo_query_gsc { siteId: , ... }
→ heyseo_top_keywords { siteId: , ... }
→ etc.
`

$3

- Data Isolation: Prevents accidentally querying wrong site's data
- Explicit Selection: User clearly knows which site they're working with
- Session Persistence: Selection persists across multiple operations
- Safety: Perfect for users managing multiple sites

---

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: support@heyseo.app