@heyseo/mcp-server 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +140 -175
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,86 +1,50 @@
1
1
  # HeySeo MCP Server
2
2
 
3
- Connect your LLM to your SEO data. Query Google Search Console, Google Analytics 4, and PageSpeed Insights directly from Claude, Cursor, or any MCP-compatible client.
3
+ 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.
4
4
 
5
- ## Features
5
+ ## Quick Start
6
6
 
7
- ### Tools
7
+ ### 1. Get your API Key
8
8
 
9
- | Tool | Description |
10
- |------|-------------|
11
- | `heyseo_query_gsc` | Query Google Search Console analytics with custom dimensions and filters |
12
- | `heyseo_top_keywords` | Get top performing keywords for a site |
13
- | `heyseo_top_pages` | Get top performing pages for a site |
14
- | `heyseo_query_ga4` | Query Google Analytics 4 data |
15
- | `heyseo_landing_pages` | Get landing page performance with engagement metrics |
16
- | `heyseo_traffic_sources` | Analyze traffic sources and channels |
17
- | `heyseo_pagespeed` | Run PageSpeed Insights analysis with Core Web Vitals |
18
- | `heyseo_pagespeed_bulk` | Analyze multiple pages at once |
19
- | `heyseo_compare_periods` | Compare SEO metrics between two time periods |
20
- | `heyseo_week_over_week` | Quick week-over-week comparison |
21
- | `heyseo_find_opportunities` | Discover SEO optimization opportunities |
22
- | `heyseo_create_task` | Create SEO tasks in HeySeo Kanban |
23
-
24
- ### Resources
25
-
26
- Access your SEO data as readable resources:
27
-
28
- - `heyseo://sites` - List all connected sites
29
- - `heyseo://sites/{id}` - Site details
30
- - `heyseo://sites/{id}/overview` - Current metrics overview
31
- - `heyseo://sites/{id}/keywords` - Top 50 keywords
32
- - `heyseo://sites/{id}/pages` - Top 50 pages
33
-
34
- ### Prompts
35
-
36
- Pre-built prompts for common SEO tasks:
37
-
38
- - `seo_audit` - Comprehensive SEO audit
39
- - `weekly_report` - Weekly performance report
40
- - `keyword_research` - Keyword analysis and opportunities
41
- - `content_optimization` - Page optimization recommendations
42
- - `technical_health_check` - Core Web Vitals and performance
43
- - `traffic_analysis` - Traffic patterns and sources
44
- - `quick_wins` - Low-effort, high-impact opportunities
45
- - `ranking_changes` - Recent ranking changes analysis
46
-
47
- ## Installation
48
-
49
- ```bash
50
- npm install @heyseo/mcp-server
51
- ```
52
-
53
- Or clone and build from source:
9
+ 1. Sign up at [heyseo.app](https://heyseo.app)
10
+ 2. Connect your Google Search Console and/or GA4 properties
11
+ 3. Go to **Settings > API** and generate an API key
54
12
 
55
- ```bash
56
- git clone https://github.com/heyseo/mcp-server
57
- cd mcp-server
58
- npm install
59
- npm run build
60
- ```
13
+ ### 2. Configure your MCP Client
61
14
 
62
- ## Configuration
15
+ Choose your client below and add the configuration:
63
16
 
64
- ### Environment Variables
17
+ <details>
18
+ <summary><strong>Claude Desktop</strong></summary>
65
19
 
66
- ```bash
67
- # Required: Your HeySeo API key
68
- HEYSEO_API_KEY=your_api_key_here
20
+ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
69
21
 
70
- # Optional: Custom API URL (defaults to https://heyseo.app)
71
- HEYSEO_API_URL=https://heyseo.app
22
+ ```json
23
+ {
24
+ "mcpServers": {
25
+ "heyseo": {
26
+ "command": "npx",
27
+ "args": ["-y", "@heyseo/mcp-server"],
28
+ "env": {
29
+ "HEYSEO_API_KEY": "your_api_key_here"
30
+ }
31
+ }
32
+ }
33
+ }
72
34
  ```
35
+ </details>
73
36
 
74
- ### Claude Desktop Configuration
37
+ <details>
38
+ <summary><strong>Claude Code (CLI)</strong></summary>
75
39
 
76
- Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
40
+ Edit `~/.claude/settings.json`:
77
41
 
78
42
  ```json
79
43
  {
80
44
  "mcpServers": {
81
45
  "heyseo": {
82
46
  "command": "npx",
83
- "args": ["@heyseo/mcp-server"],
47
+ "args": ["-y", "@heyseo/mcp-server"],
84
48
  "env": {
85
49
  "HEYSEO_API_KEY": "your_api_key_here"
86
50
  }
@@ -88,15 +52,19 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
88
52
  }
89
53
  }
90
54
  ```
55
+ </details>
91
56
 
92
- Or if installed locally:
57
+ <details>
58
+ <summary><strong>Cursor</strong></summary>
59
+
60
+ Edit your Cursor MCP settings:
93
61
 
94
62
  ```json
95
63
  {
96
64
  "mcpServers": {
97
65
  "heyseo": {
98
- "command": "node",
99
- "args": ["/path/to/mcp-server/dist/index.js"],
66
+ "command": "npx",
67
+ "args": ["-y", "@heyseo/mcp-server"],
100
68
  "env": {
101
69
  "HEYSEO_API_KEY": "your_api_key_here"
102
70
  }
@@ -104,17 +72,19 @@ Or if installed locally:
104
72
  }
105
73
  }
106
74
  ```
75
+ </details>
107
76
 
108
- ### Cursor Configuration
77
+ <details>
78
+ <summary><strong>Windsurf</strong></summary>
109
79
 
110
- Add to your Cursor settings:
80
+ Edit `~/.codeium/windsurf/mcp_config.json`:
111
81
 
112
82
  ```json
113
83
  {
114
- "mcp.servers": {
84
+ "mcpServers": {
115
85
  "heyseo": {
116
86
  "command": "npx",
117
- "args": ["@heyseo/mcp-server"],
87
+ "args": ["-y", "@heyseo/mcp-server"],
118
88
  "env": {
119
89
  "HEYSEO_API_KEY": "your_api_key_here"
120
90
  }
@@ -122,153 +92,148 @@ Add to your Cursor settings:
122
92
  }
123
93
  }
124
94
  ```
95
+ </details>
125
96
 
126
- ## Usage Examples
97
+ <details>
98
+ <summary><strong>ChatGPT Desktop</strong></summary>
127
99
 
128
- ### Query Top Keywords
100
+ ChatGPT Desktop supports MCP servers. Add to your settings:
129
101
 
102
+ ```json
103
+ {
104
+ "mcpServers": {
105
+ "heyseo": {
106
+ "command": "npx",
107
+ "args": ["-y", "@heyseo/mcp-server"],
108
+ "env": {
109
+ "HEYSEO_API_KEY": "your_api_key_here"
110
+ }
111
+ }
112
+ }
113
+ }
130
114
  ```
131
- User: What are my top 10 keywords this month?
132
-
133
- Claude: I'll query your top keywords using HeySeo.
134
- [Calls heyseo_top_keywords with limit=10]
115
+ </details>
135
116
 
136
- Here are your top 10 keywords for the last 28 days:
137
-
138
- | Rank | Keyword | Clicks | Impressions | CTR | Position |
139
- |------|---------|--------|-------------|-----|----------|
140
- | 1 | seo tools | 1,234 | 45,000 | 2.7% | 4.2 |
141
- | 2 | keyword research | 890 | 32,000 | 2.8% | 5.1 |
142
- ...
143
- ```
117
+ <details>
118
+ <summary><strong>Local Development</strong></summary>
144
119
 
145
- ### Run SEO Audit
120
+ If you're running from source:
146
121
 
122
+ ```json
123
+ {
124
+ "mcpServers": {
125
+ "heyseo": {
126
+ "command": "node",
127
+ "args": ["/path/to/mcp-server/dist/index.js"],
128
+ "env": {
129
+ "HEYSEO_API_KEY": "your_api_key_here"
130
+ }
131
+ }
132
+ }
133
+ }
147
134
  ```
148
- User: Run an SEO audit on my site
149
-
150
- Claude: I'll perform a comprehensive SEO audit.
151
- [Uses seo_audit prompt template]
152
- [Calls multiple tools: top_keywords, top_pages, find_opportunities]
153
-
154
- ## SEO Audit Report
135
+ </details>
155
136
 
156
- ### Performance Overview
157
- - Total Clicks: 15,234 (+12% MoM)
158
- - Impressions: 456,000 (+8% MoM)
159
- - Average CTR: 3.3%
160
- - Average Position: 12.4
137
+ > **Note:** The `-y` flag is required for npx to skip installation prompts, which would otherwise cause the server to hang.
161
138
 
162
- ### Key Findings
163
- 1. **Quick Wins Found**: 23 keywords with high impressions but low CTR
164
- 2. **Page 2 Opportunities**: 15 keywords ranking positions 11-20
165
- 3. **Underperforming Pages**: 5 pages with >1000 impressions but <2% CTR
139
+ ### 3. Restart your client
166
140
 
167
- ### Recommendations
168
- 1. [HIGH] Optimize meta descriptions for top 10 low-CTR pages
169
- 2. [MEDIUM] Expand content on page 2 keywords
170
- 3. [LOW] Add FAQ schema to product pages
141
+ Restart Claude Desktop, Cursor, or your MCP client to load the new server.
171
142
 
172
- Creating tasks for top recommendations...
173
- ```
174
-
175
- ### Compare Performance
176
-
177
- ```
178
- User: How did we do this week vs last week?
143
+ ---
179
144
 
180
- Claude: I'll compare your week-over-week performance.
181
- [Calls heyseo_week_over_week]
145
+ ## Available Tools
182
146
 
183
- ## Week-over-Week Comparison
184
-
185
- | Metric | Last Week | This Week | Change |
186
- |--------|-----------|-----------|--------|
187
- | Clicks | 3,456 | 3,890 | +12.6% |
188
- | Impressions | 98,000 | 105,000 | +7.1% |
189
- | CTR | 3.5% | 3.7% | +0.2pp |
190
- | Position | 11.2 | 10.8 | -0.4 (improved) |
147
+ | Tool | Description |
148
+ |------|-------------|
149
+ | `heyseo_query_gsc` | Query Google Search Console with custom dimensions and filters |
150
+ | `heyseo_top_keywords` | Get top performing keywords for a site |
151
+ | `heyseo_top_pages` | Get top performing pages for a site |
152
+ | `heyseo_query_ga4` | Query Google Analytics 4 data |
153
+ | `heyseo_landing_pages` | Get landing page performance with engagement metrics |
154
+ | `heyseo_traffic_sources` | Analyze traffic sources and channels |
155
+ | `heyseo_pagespeed` | Run PageSpeed Insights analysis with Core Web Vitals |
156
+ | `heyseo_pagespeed_bulk` | Analyze multiple pages at once |
157
+ | `heyseo_compare_periods` | Compare SEO metrics between two time periods |
158
+ | `heyseo_week_over_week` | Quick week-over-week comparison |
159
+ | `heyseo_find_opportunities` | Discover SEO optimization opportunities |
160
+ | `heyseo_create_task` | Create SEO tasks in HeySeo Kanban |
191
161
 
192
- **Top Gainers:**
193
- - "best seo tool" +45 clicks (+32%)
194
- - "keyword tracker" +28 clicks (+18%)
162
+ ## Resources
195
163
 
196
- **Top Losers:**
197
- - "seo software" -12 clicks (-8%)
198
- ```
164
+ Access your SEO data as readable resources:
199
165
 
200
- ### Analyze Page Speed
166
+ | URI | Description |
167
+ |-----|-------------|
168
+ | `heyseo://sites` | List all connected sites |
169
+ | `heyseo://sites/{id}` | Site details |
170
+ | `heyseo://sites/{id}/overview` | Current metrics overview |
171
+ | `heyseo://sites/{id}/keywords` | Top 50 keywords |
172
+ | `heyseo://sites/{id}/pages` | Top 50 pages |
201
173
 
202
- ```
203
- User: Check the page speed for our homepage
174
+ ## Prompts
204
175
 
205
- Claude: I'll analyze your homepage performance.
206
- [Calls heyseo_pagespeed with url and strategy=mobile]
176
+ Pre-built prompts for common SEO tasks:
207
177
 
208
- ## PageSpeed Analysis: https://example.com
178
+ | Prompt | Description |
179
+ |--------|-------------|
180
+ | `seo_audit` | Comprehensive SEO audit |
181
+ | `weekly_report` | Weekly performance report |
182
+ | `keyword_research` | Keyword analysis and opportunities |
183
+ | `content_optimization` | Page optimization recommendations |
184
+ | `technical_health_check` | Core Web Vitals and performance |
185
+ | `traffic_analysis` | Traffic patterns and sources |
186
+ | `quick_wins` | Low-effort, high-impact opportunities |
187
+ | `ranking_changes` | Recent ranking changes analysis |
209
188
 
210
- **Performance Score: 72/100** (Needs Improvement)
189
+ ---
211
190
 
212
- ### Core Web Vitals
213
- | Metric | Value | Rating |
214
- |--------|-------|--------|
215
- | LCP | 2.8s | Needs Improvement |
216
- | INP | 120ms | Good |
217
- | CLS | 0.05 | Good |
218
- | FCP | 1.2s | Good |
219
- | TTFB | 0.8s | Good |
191
+ ## Usage Examples
220
192
 
221
- ### Top Opportunities
222
- 1. **Serve images in next-gen formats** - Save 1.2s
223
- 2. **Eliminate render-blocking resources** - Save 0.8s
224
- 3. **Reduce unused JavaScript** - Save 0.4s
193
+ **Get top keywords:**
194
+ > "What are my top 10 keywords this month?"
225
195
 
226
- Would you like me to create tasks for these optimizations?
227
- ```
196
+ **Run an SEO audit:**
197
+ > "Run an SEO audit on my site"
228
198
 
229
- ## API Reference
199
+ **Compare performance:**
200
+ > "How did we do this week vs last week?"
230
201
 
231
- ### Getting an API Key
202
+ **Analyze page speed:**
203
+ > "Check the page speed for our homepage"
232
204
 
233
- 1. Sign up at [heyseo.app](https://heyseo.app)
234
- 2. Connect your Google Search Console and/or GA4 properties
235
- 3. Generate an API key in Settings > API
205
+ **Find opportunities:**
206
+ > "Find quick win SEO opportunities"
236
207
 
237
- ### Rate Limits
208
+ ---
238
209
 
239
- - 100 requests per minute per API key
240
- - 10,000 requests per day per API key
210
+ ## Environment Variables
241
211
 
242
- ### Error Handling
212
+ | Variable | Required | Default | Description |
213
+ |----------|----------|---------|-------------|
214
+ | `HEYSEO_API_KEY` | Yes | - | Your HeySeo API key |
215
+ | `HEYSEO_API_URL` | No | `https://heyseo.app` | Custom API URL |
243
216
 
244
- All tools return JSON with a `success` field:
217
+ ## Rate Limits
245
218
 
246
- ```json
247
- // Success
248
- {
249
- "success": true,
250
- "data": { ... }
251
- }
219
+ - 100 requests per minute
220
+ - 10,000 requests per day
252
221
 
253
- // Error
254
- {
255
- "success": false,
256
- "error": "Error message here"
257
- }
258
- ```
222
+ ---
259
223
 
260
224
  ## Development
261
225
 
262
226
  ```bash
227
+ # Clone the repo
228
+ git clone https://github.com/heyseo/mcp-server
229
+ cd mcp-server
230
+
263
231
  # Install dependencies
264
232
  npm install
265
233
 
266
234
  # Build
267
235
  npm run build
268
236
 
269
- # Run in development mode
270
- npm run dev
271
-
272
237
  # Test locally
273
238
  HEYSEO_API_KEY=your_key node dist/index.js
274
239
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@heyseo/mcp-server",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "HeySeo MCP Server - Connect LLMs to your SEO data",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",