# @seomcp/proxy

Local MCP proxy for [seo-mcp](https://github.com/quantacodes/seo-mcp) — 39 SEO tools in your AI assistant.

Reads your Google service account credentials from disk and forwards MCP tool calls to `api.seomcp.dev` over HTTPS. Zero runtime dependencies, single-file bundle, ~11KB.

## Quick Start

```bash
npm i -g github:quantacodes/seomcp-proxy
```

### Configure Your MCP Client

Add to your Claude Desktop, Cursor, or other MCP client config:

```json
{
  "mcpServers": {
    "seo-mcp": {
      "command": "seomcp-proxy",
      "env": {
        "SEOMCP_API_KEY": "sk_live_...",
        "GOOGLE_SERVICE_ACCOUNT": "/path/to/service-account.json",
        "GSC_PROPERTIES": "example.com,blog.example.com",
        "GA4_PROPERTIES": "123456789:example.com,987654321:blog.example.com"
      }
    }
  }
}
```

### Verify Setup

```bash
export SEOMCP_API_KEY="sk_live_..."
export GOOGLE_SERVICE_ACCOUNT="/path/to/service-account.json"
seomcp-proxy test
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SEOMCP_API_KEY` | ✅ | API key from [seomcp.dev/dashboard](https://seomcp.dev/dashboard) |
| `GOOGLE_SERVICE_ACCOUNT` | ✅ | Path to Google service account JSON file |
| `GSC_PROPERTIES` | Required for GSC tools | Comma-separated domain names (e.g., `example.com,blog.example.com`) - we auto-add `sc-domain:` |
| `GA4_PROPERTIES` | Required for GA4 tools | Comma-separated with domain mapping: `propertyID:domain` (e.g., `123:example.com,456:blog.example.com`) |
| `SEOMCP_API_URL` | Optional | Override API URL (default: `https://api.seomcp.dev`) |
| `SEOMCP_TIMEOUT` | Optional | Request timeout in ms (default: `30000`) |

**Property Mapping:** 
- `GA4_PROPERTIES`: Use `propertyID:domain` format for explicit mapping
- `GSC_PROPERTIES`: Just list domain names, we automatically format them as `sc-domain:example.com`

```
GSC_PROPERTIES=example.com,blog.example.com
GA4_PROPERTIES=123456789:example.com,987654321:blog.example.com
# example.com ↔ 123456789, blog.example.com ↔ 987654321
```

## CLI Commands

```bash
seomcp-proxy              # Run as MCP server (stdio mode)
seomcp-proxy test         # Validate credentials + API key + connectivity
seomcp-proxy version      # Print version
seomcp-proxy --help       # Print help
```

## 📊 SEO Report Skill (Bundled)

This repo includes the **seo-mcp-reports** skill — a comprehensive knowledge pack that teaches AI agents how to generate professional, agency-quality SEO reports with charts, styled tables, and visual dashboards.

### What's Included

```
skills/seo-mcp-reports/
├── SKILL.md                      # Quick start + base design system
└── references/
    ├── templates.md              # Full HTML/CSS/Chart.js templates for 6 report types
    ├── analysis.md               # Data processing functions (CWV, CTR, cannibalization)
    └── setup.md                  # Setup guide, all 39 tools, pricing, troubleshooting
```

### Report Types

| Type | Time | Best For |
|------|------|----------|
| Weekly | 10 min | Regular monitoring |
| Monthly | 30 min | Client deliverables |
| Quarterly | 2 hrs | Strategy reviews |
| Technical | 20 min | Troubleshooting |
| Competitive | 45 min | Strategy planning |
| Agency (Client-Friendly) | 40 min | Non-technical stakeholders |

### How to Use

See **[INSTALL.md](skills/seo-mcp-reports/INSTALL.md)** for setup instructions for:

- **Claude Code** — project-level or global CLAUDE.md
- **Claude Desktop** — project knowledge + custom instructions
- **Cursor** — .cursor/rules or .cursorrules
- **VSCode + Continue.dev** — .continuerules + context providers
- **OpenClaw** — drop into workspace skills/
- **Windsurf / Other agents** — universal setup pattern

---

## 39 Tools Available

### Crawling & Audit (3)
`site_audit` · `crawl_page` · `test_robots_txt`

### Google Search Console (8)
`gsc_performance` · `gsc_list_sites` · `gsc_list_sitemaps` · `gsc_submit_sitemap` · `gsc_delete_sitemap` · `gsc_inspect_url` · `gsc_bulk_inspect` · `gsc_search_appearances`

### Google Analytics 4 (11)
`ga4_list_properties` · `ga4_report` · `ga4_batch_report` · `ga4_funnel_report` · `ga4_realtime` · `ga4_metadata` · `ga4_overview` · `ga4_top_pages` · `ga4_traffic_sources` · `ga4_devices` · `ga4_geography`

### Core Web Vitals (1)
`core_web_vitals`

### Schema & Structured Data (2)
`validate_schema` · `analyze_robots_txt`

### Sitemaps (1)
`sitemap_index_diff`

### IndexNow (4)
`indexnow_submit_url` · `indexnow_batch_submit` · `indexnow_submit_sitemap` · `indexnow_submit_file`

### Google Indexing API (4)
`google_indexing_submit_url` · `google_indexing_batch_submit` · `google_indexing_submit_sitemap` · `google_indexing_submit_file`

### Utility (2)
`quota_status` · `healthcheck`

### Reports (1)
`generate_report`

### Meta (1)
`version`

## How It Works

```
Your AI (Claude, Cursor, etc.)
  ↕ JSON-RPC over stdio
@seomcp/proxy (this package)
  ↕ HTTPS with credentials
api.seomcp.dev
  ↕ runs seo-mcp binary
Google APIs (GSC, GA4, PageSpeed)
```

1. Your MCP client sends a `tools/call` request over stdin
2. The proxy reads your Google service account from disk (fresh every call)
3. Forwards the tool call + credentials to `api.seomcp.dev` over HTTPS
4. Returns the result to your MCP client over stdout

**Credentials are re-read on every request** — rotate your service account keys without restarting.

## Google Service Account Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a service account (or use existing)
3. Enable APIs: Search Console API, Analytics Data API, PageSpeed Insights API
4. Download the JSON key file
5. Share your GSC property with the service account email (Viewer role)
6. Add the service account to your GA4 property (Viewer role)

## Security

- Credentials are transmitted over HTTPS only
- Service account JSON is re-read from disk per request (never cached in memory)
- API key validated locally before any network call
- The cloud API does not log or persist credentials

## Requirements

- Node.js ≥ 18
- Google service account with GSC/GA4 access
- API key from [seomcp.dev](https://seomcp.dev)

## License

MIT © [quantacodes](https://github.com/quantacodes)