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

2. Service Account with a downloaded JSON key file:

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

3. 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