HeySeo MCP Server - Connect LLMs to your SEO data
npm install @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.
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
Choose your client below and add the configuration:
Claude Desktop
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"
}
}
}
}
Claude Code (CLI)
Edit ~/.claude/settings.json:
`json`
{
"mcpServers": {
"heyseo": {
"command": "npx",
"args": ["-y", "@heyseo/mcp-server"],
"env": {
"HEYSEO_API_KEY": "your_api_key_here"
}
}
}
}
Cursor
Edit your Cursor MCP settings:
`json`
{
"mcpServers": {
"heyseo": {
"command": "npx",
"args": ["-y", "@heyseo/mcp-server"],
"env": {
"HEYSEO_API_KEY": "your_api_key_here"
}
}
}
}
Windsurf
Edit ~/.codeium/windsurf/mcp_config.json:
`json`
{
"mcpServers": {
"heyseo": {
"command": "npx",
"args": ["-y", "@heyseo/mcp-server"],
"env": {
"HEYSEO_API_KEY": "your_api_key_here"
}
}
}
}
ChatGPT Desktop
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"
}
}
}
}
Local Development
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"
}
}
}
}
> Note: The -y flag is required for npx to skip installation prompts, which would otherwise cause the server to hang.
Restart Claude Desktop, Cursor, or your MCP client to load the new server.
---
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 |
| 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) |
| 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 |
| Tool | Description |
|------|-------------|
| heyseo_pagespeed | Run PageSpeed Insights analysis with Core Web Vitals |heyseo_pagespeed_bulk
| | Analyze multiple pages at once |
| 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 |
| 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) |
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 |
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 |
---
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?"
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"
---
The HeySeo MCP server uses explicit site selection to prevent data isolation issues:
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.
- 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
---
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| HEYSEO_API_KEY | Yes | - | Your HeySeo API key |HEYSEO_API_URL
| | No | https://www.heyseo.app` | Custom API URL |
- 100 requests per minute
- 10,000 requests per day
---
MIT
- Website: heyseo.app
- Email: support@heyseo.app