git clone https://github.com/serpfire/gsc-mcp-server.git
cd gsc-mcp-server
npm install

GSC_OAUTH_CLIENT_ID=your-client-id \
GSC_OAUTH_CLIENT_SECRET=your-client-secret \
npm run setup

claude mcp add --transport stdio gsc -s user \
  -e GSC_OAUTH_CLIENT_ID=your-client-id \
  -e GSC_OAUTH_CLIENT_SECRET=your-client-secret \
  -- node /absolute/path/to/gsc-mcp-server/src/index.js

{
  "mcpServers": {
    "gsc": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gsc-mcp-server/src/index.js"],
      "env": {
        "GSC_OAUTH_CLIENT_ID": "your-client-id",
        "GSC_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

{
  "env": {
    "GSC_AUTH_MODE": "service_account",
    "GSC_SERVICE_ACCOUNT_KEY_PATH": "/path/to/key.json"
  }
}

src/
├── index.js                          # Entry: auth -> client -> db -> server -> stdio
├── server.js                         # McpServer factory
├── auth/
│   ├── index.js                      # Auth factory (auto-detects mode from env)
│   ├── service-account.js            # Service account key file auth
│   ├── oauth.js                      # Browser flow + token persistence + auto-recovery
│   ├── token-store.js                # ~/.gsc-mcp/tokens.json
│   └── setup.js                      # Standalone setup script
├── gsc/                              # Pure GSC API wrappers (no MCP knowledge)
│   ├── client.js
│   ├── sites.js
│   ├── search-analytics.js
│   ├── sitemaps.js
│   └── url-inspection.js
├── db/
│   ├── connection.js                 # SQLite setup with WAL mode
│   └── schema.js                     # Migrations
├── analysis/                         # SEO analysis engine (uses local SQLite)
│   ├── sync.js                       # GSC API -> SQLite incremental sync
│   ├── low-hanging-fruit.js          # Opportunity scoring
│   ├── cannibalization.js            # HHI-based detection
│   ├── trending.js                   # PoP / YoY trending queries & pages
│   ├── traffic-drop.js              # Multi-view drop diagnostics
│   ├── group-performance.js          # Group-level aggregation
│   ├── auto-segment.js              # Automatic URL segmentation
│   ├── auto-group.js                # Automatic query grouping
│   ├── shared.js                     # Shared SQL helpers
│   ├── groups/
│   │   ├── manager.js                # CRUD for groups + rules
│   │   ├── compiler.js               # OR/AND/NOT rule compilation
│   │   └── matcher.js                # Regex matching engine
│   └── semantic/
│       ├── discover.js               # Cluster discovery orchestrator
│       ├── clustering.js             # Connected components algorithm
│       ├── similarity.js             # Multi-signal similarity scoring
│       └── labeler.js                # Cluster naming
├── tools/
│   ├── definitions.js                # Core GSC tools (declarative)
│   ├── analysis-definitions.js       # Analysis tools (declarative)
│   ├── middleware.js                  # Rate limiting + error handling wrapper
│   ├── auth.js                       # switch_account tool
│   └── index.js                      # Registration loop
├── resources.js                      # sites://list resource
├── prompts.js                        # SEO analysis + index check prompts
└── utils/
    ├── logger.js                     # stderr-only (stdout = MCP protocol)
    ├── errors.js                     # Google API error -> MCP error
    ├── constants.js                  # Scopes, rate limits, defaults
    ├── rate-limiter.js               # Sliding window
    └── open-url.js                   # Cross-platform browser opener

npm run inspect