mcp-site-analyst

MCP Site Analyst

An MCP (Model Context Protocol) server that provides Google Analytics (GA4) and Google Search Console data as tools for AI assistants.

Features

• 13 tools across two Google services
• Google Analytics (GA4): Custom reports, realtime data, metadata discovery, top pages, traffic sources, demographics
• Google Search Console: Search analytics, sitemaps, URL inspection, site listing, top queries, top pages
• Dual transport: stdio (local) and stateless HTTP (remote)
• Flexible auth: Service account key file, inline JSON credentials, Application Default Credentials, or CLI argument
• Configurable GA4 Property ID: Set once at server level or per-tool call
• Optional Bearer token auth for HTTP mode

Prerequisites

1. Google Cloud Project with these APIs enabled:

• Google Analytics Data API
• Google Search Console API

1. Service Account with a downloaded JSON key file:

• Go to IAM & Admin > Service Accounts
• Create a service account → Keys → Add Key → JSON

1. Grant access to the service account:

• GA4: Admin > Property Access Management > Add the service account email as Viewer
• Search Console: Settings > Users and permissions > Add the service account email

Installation

npm install
npm run build

Usage

stdio mode (Claude Desktop, Gemini CLI, etc.)

# Using CLI argument
node build/index.js --key-file /path/to/key.json

# Using environment variable
GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json node build/index.js

# With a default GA4 Property ID
node build/index.js --key-file /path/to/key.json --property-id 123456789

HTTP mode

# Default port 3000
node build/index.js --http --key-file /path/to/key.json

# Custom port
node build/index.js --http --port 8080 --key-file /path/to/key.json

# With Bearer token authentication
MCP_AUTH_TOKEN=my-secret-token node build/index.js --http --key-file /path/to/key.json

The HTTP endpoint is available at POST http://localhost:3000/mcp (Streamable HTTP, stateless). A health check endpoint is available at GET http://localhost:3000/health.

Authentication

The server resolves Google credentials in this order:

| Priority | Method | Description | |----------|--------|-------------| | 1 | --key-file <path> | CLI argument pointing to a service account JSON key file | | 2 | GOOGLE_CREDENTIALS_JSON | Environment variable containing the full JSON key as a string (useful for containers/CI) | | 3 | GOOGLE_APPLICATION_CREDENTIALS | Environment variable pointing to a key file path | | 4 | Application Default Credentials | Automatic on Cloud Run, GCE, or when authenticated via gcloud auth application-default login |

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "site-analyst": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-site-analyst/build/index.js",
        "--key-file",
        "/absolute/path/to/key.json",
        "--property-id",
        "YOUR_GA4_PROPERTY_ID"
      ]
    }
  }
}

Gemini CLI Configuration

Add to your .gemini/settings.json:

{
  "mcpServers": {
    "site-analyst": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-site-analyst/build/index.js",
        "--key-file",
        "/absolute/path/to/key.json"
      ]
    }
  }
}

Remote HTTP Configuration

If deployed to a remote server (e.g. Cloud Run), configure your client to use the HTTP endpoint:

{
  "mcpServers": {
    "site-analyst": {
      "httpUrl": "https://your-service-url/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
      }
    }
  }
}

Deploying to Cloud Run

A deployment script is included for Google Cloud Run.

Setup

# Copy the example env file and fill in your values
cp .env.example .env

# Edit .env with your GCP project ID, region, and GA4 property ID

See .env.example for all available configuration options.

Deploy

# Deploy with Cloud Build (no local Docker required)
./deploy.sh --cloud-build

# Deploy with local Docker build
./deploy.sh

# Deploy with Bearer token auth enabled
./deploy.sh --token "my-secret-token"

On Cloud Run the server uses Application Default Credentials automatically via the configured service account — no key file is needed.

Tools Reference

Google Analytics (GA4)

| Tool | Description | |------|-------------| | ga4_run_report | Run a custom report with flexible dimensions, metrics, date ranges, filters, and sorting | | ga4_realtime_report | Get real-time active user data (last 30 minutes) | | ga4_get_metadata | Discover all available dimensions and metrics | | ga4_top_pages | Shortcut: Top pages by pageviews | | ga4_top_traffic_sources | Shortcut: Top traffic sources by sessions | | ga4_user_demographics | Shortcut: User breakdown by country/city/language |

Google Search Console

| Tool | Description | |------|-------------| | gsc_search_analytics | Query search performance (clicks, impressions, CTR, position) with filters | | gsc_list_sitemaps | List all submitted sitemaps | | gsc_get_sitemap | Get details for a specific sitemap | | gsc_inspect_url | Inspect a URL's index status and mobile usability | | gsc_list_sites | List all sites accessible by the service account | | gsc_top_queries | Shortcut: Top search queries by clicks | | gsc_top_pages | Shortcut: Top pages by clicks in search |

Development

# Run in dev mode (no build step needed)
npx tsx src/index.ts --key-file /path/to/key.json

# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js --key-file /path/to/key.json

License

MIT