wingolf-ai-mcp

MCP server for wingolf.vn — integrates Google Search Console, Google Analytics 4, and GitHub into a single MCP endpoint for AI clients (Claude, ChatGPT, Cursor, Codex).

Features

• Google Search Console — search analytics, top queries, top pages
• Google Analytics 4 — flexible reports, traffic summary, top pages
• GitHub — code search, file contents, recent commits, pull requests
• Dual transport: stdio (local) and Streamable HTTP (deploy)
• Bearer token auth on HTTP transport
• Read-only by design — no data deletion or modification

Quick Start (local)

1. Prerequisites

• Node.js 20+
• A Google Cloud project with Search Console API and Analytics Data API enabled
• A GitHub fine-grained personal access token

2. Clone and install

cd wingolf-ai-mcp
cp .env.example .env
npm install

3. Configure environment

Edit .env and fill in your credentials (see sections below).

4. Run

# stdio mode (for Claude Desktop / Cursor / Codex)
npm run start:stdio

# HTTP mode (for remote clients or testing)
npm run start:http

# Dev with auto-reload
npm run dev

---

Google Setup

Create a Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Note the Project ID

Enable APIs

1. Go to APIs & Services → Library
2. Search for and enable:
   • Google Search Console API
   • Google Analytics Data API

Create a Service Account

1. Go to IAM & Admin → Service Accounts
2. Click Create Service Account
3. Give it a name (e.g., mcp-server)
4. Assign role: Viewer (or create a custom role with minimal permissions)
5. Click Done
6. Click the service account → Keys → Add Key → Create New Key → JSON
7. Save the downloaded JSON file to secrets/google-service-account.json

Never commit this file! The .env.example path is /app/secrets/google-service-account.json which is mounted read-only via Docker.

Add Service Account to Search Console

1. Go to Google Search Console
2. Select your property (e.g., https://wingolf.vn/)
3. Go to Settings → Users and permissions
4. Click Add user
5. Enter the service account email (found in the JSON key file, looks like name@project.iam.gserviceaccount.com)
6. Set permission to Restricted (or Full — Restricted is enough for read-only)
7. Click Add

Add Service Account to GA4

1. Go to Google Analytics
2. Select your GA4 property
3. Go to Admin → Property Access Management
4. Click + → Add users
5. Enter the service account email
6. Select role: Viewer (or Analyst)
7. Click Add

Find your GA4 Property ID

1. In GA4 Admin, under Property Settings → Property Details
2. Copy the numeric Property ID (e.g., 123456789)
3. Set GA4_PROPERTY_ID=123456789 in your .env

---

GitHub Setup

Create Fine-Grained PAT

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Click Generate new token
3. Set:
   • Token name: wingolf-ai-mcp
   • Expiration: as needed
   • Resource owner: your org or user
   • Repository access: Only select repositories → choose your repo
4. Under Permissions → Repository permissions, set:
   • Contents: Read-only
   • Metadata: Read-only (auto-selected)
   • Pull requests: Read-only
5. Click Generate token and copy it

Set in .env:

GITHUB_TOKEN=github_pat_xxx
GITHUB_OWNER=your-org-or-user
GITHUB_REPO=your-repo

---

Docker Deployment

Build and run

# Build
docker compose build

# Run
docker compose up -d

# View logs
docker compose logs -f

Directory structure on VPS

~/wingolf-ai-mcp/
├── docker-compose.yml
├── .env
└── secrets/
    └── google-service-account.json   # ro-mounted

Behind Nginx / Cloudflare

For production, put the container behind Nginx or Cloudflare Tunnel with HTTPS:

location /mcp {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

---

Connecting AI Clients

ChatGPT Connector

1. Open ChatGPT → Settings → Connectors → Create
2. Enter Connector URL: https://tours.ct14a1.fun/mcp
3. If connected successfully, the tools list will appear automatically

This server uses anonymous/no-auth for dev mode. For production OAuth 2.1, see OpenAI MCP Auth docs.

Claude Desktop (local stdio)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "wingolf-ai-mcp": {
      "command": "node",
      "args": ["path/to/wingolf-ai-mcp/dist/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/secrets/google-service-account.json",
        "GSC_SITE_URL": "https://wingolf.vn/",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

Cursor / Windsurf / Other MCP Clients

Transport: Streamable HTTP
URL: https://tours.ct14a1.fun/mcp

---

Testing with curl

# Health (no auth needed)
curl https://mcp.example.com/health

# Ready (needs auth)
curl -H "Authorization: Bearer your-token" https://mcp.example.com/ready

# MCP endpoint
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  https://mcp.example.com/mcp

---

Available Tools

Tool	Description
gsc_search_analytics	Full GSC search analytics query with dimensions, filters, pagination
gsc_top_queries	Top search queries by clicks/impressions
gsc_top_pages	Top landing pages by clicks/impressions
ga4_run_report	Flexible GA4 report with custom dimensions and metrics
ga4_traffic_summary	Traffic summary by channel group
ga4_top_pages	Top pages by page views
github_search_code	Search code in repository
github_get_file	Fetch file contents with decoded text
github_list_recent_commits	List recent commits
github_list_pull_requests	List pull requests by state
health_check	Server health and configuration status

---

Environment Variables

Variable	Required	Default	Description
PORT	No	8787	HTTP server port
MCP_BEARER_TOKEN	Yes	—	Bearer token for HTTP transport auth
GOOGLE_APPLICATION_CREDENTIALS	For GSC/GA4	—	Path to service account JSON key file
GSC_SITE_URL	For GSC	—	Search Console property URL
GA4_PROPERTY_ID	For GA4	—	GA4 property numeric ID
GITHUB_TOKEN	For GitHub	—	GitHub fine-grained PAT
GITHUB_OWNER	For GitHub	—	GitHub org or username
GITHUB_REPO	For GitHub	—	GitHub repository name
ENABLE_GITHUB_WRITE_TOOLS	No	false	Enable GitHub write tools (future)
MCP_TRANSPORT	No	stdio	Transport mode (stdio or http)

---

Security Notes

• Rotate tokens regularly — use unique bearer tokens per environment
• Never commit secrets — .env and secrets/ are excluded from git
• Read-only by design — all tools are annotated readOnlyHint: true
• Use HTTPS — put behind Cloudflare, Nginx, or Caddy in production
• IP allowlist — restrict access to known IPs if possible
• GitHub write tools are disabled by default (ENABLE_GITHUB_WRITE_TOOLS=false)
• No shell commands are executed by any tool
• No arbitrary file reading — only the configured service account JSON is read

---

Project Structure

wingolf-ai-mcp/
├── package.json
├── tsconfig.json
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── README.md
└── src/
    ├── index.ts              # Entry point
    ├── server.ts             # McpServer factory
    ├── transports/
    │   ├── stdio.ts          # Stdio transport
    │   └── http.ts           # HTTP transport with Bearer auth
    ├── config/
    │   └── env.ts            # Environment config & validation
    ├── auth/
    │   └── bearer.ts         # Bearer token extraction & validation
    ├── clients/
    │   ├── gsc.ts            # Google Search Console API client
    │   ├── ga4.ts            # Google Analytics 4 API client
    │   └── github.ts         # GitHub API client (Octokit)
    ├── tools/
    │   ├── gsc.tools.ts      # GSC tool registrations
    │   ├── ga4.tools.ts      # GA4 tool registrations
    │   ├── github.tools.ts   # GitHub tool registrations
    │   └── index.ts          # Tool registration aggregator + health_check
    └── utils/
        ├── dates.ts          # Date parsing & validation
        └── errors.ts         # Error normalization

Scripts

Script	Description
npm run dev	Watch mode with tsx
npm run build	Compile TypeScript to dist/
npm run start	Run compiled server (default: stdio)
npm run start:stdio	Force stdio transport
npm run start:http	Force HTTP transport

License

MIT