MCP Servers Setup Guide

Status: Production Ready
Last Updated: December 2024

This guide covers setting up MCP (Model Context Protocol) servers for AI-assisted development in Cursor IDE and Claude Desktop.

Table of Contents

Overview

MCP servers extend AI assistants with external tools and data access. We use several MCP servers:

Server Purpose Config Location
postgres-* Database access (dev, production, replica) User config (~/.cursor/mcp.json)
google-analytics GA4 reporting and insights User config
appsignal Error tracking and APM User config
context7 Library documentation lookup Project config (.cursor/mcp.json)
heatwave WarmlyYours semantic search Project config

Two config files:

  • ~/.cursor/mcp.json — Personal credentials (not in git)
  • .cursor/mcp.json — Shared project config (in git)

Prerequisites

Required

  1. Docker Desktop — For database MCP servers

    brew install --cask docker

  2. 1Password CLI — For secure credential storage

    brew install --cask 1password-cli
op signin

  3. jq — JSON processing

    brew install jq

  4. pipx — For Python-based MCP servers (Google Analytics)

    brew install pipx
pipx ensurepath

Optional

  • gum — Interactive terminal UI for setup script 
    brew install gum

Quick Start (Cursor)

One-Command Setup

eval $(op signin) && ./script/setup_mcp_servers.sh --all

This configures all MCP servers using credentials from 1Password. Restart Cursor after running.

Interactive Setup

./script/setup_mcp_servers.sh

Select which servers to install using the interactive menu.

Specific Servers Only

./script/setup_mcp_servers.sh postgres google-analytics

List Available Servers

./script/setup_mcp_servers.sh --list

Quick Start (Claude Desktop)

Claude Desktop (the standalone macOS app) reads MCP server definitions
only from ~/Library/Application Support/Claude/claude_desktop_config.json.
It does not read project-level .mcp.json — that's a Claude Code /
Cursor / Zed convention. bin/setup bridges the two so the same server
list is available everywhere.

1. Install Claude Desktop

Download from: https://claude.ai/download

2. Run bin/setup (or bin/setup --claude-app)

The full setup script does three Claude-Desktop-specific things, in order:

  1. Populates .env.mcp from the team 1Password vault
    (script/setup_mcp_servers.sh).
  2. Installs the wrapper + Dock tile — symlinks bin/claude-desktop
    into ~/bin/, builds ~/Applications/Claude (Heatwave).app, and
    pins it to the Dock. The wrapper sources .env.mcp and
    .env.mcp.local before launching /Applications/Claude.app so the
    secrets propagate into MCP child processes.
  3. Syncs .mcp.json → claude_desktop_config.json
    (script/sync_claude_desktop_config.sh). Substitutes ${VAR}
    placeholders from .env.mcp, resolves uvx/npx/docker/… to
    absolute paths (Claude Desktop launched from the Dock has only the
    system default PATH), drops "disabled": true entries, and writes
    the result into Claude Desktop's config — replacing only the
    mcpServers key, preserving every other top-level key (preferences,
    chromeExtension, window-state, etc.). The previous file is backed
    up to .bak.

To re-run just the Claude Desktop steps without redoing brew/mise/bundle/yarn:

bin/setup --claude-app

To refresh credentials only (1Password → .env.mcp → Claude Desktop):

bin/setup --refresh-mcp

3. Launch Claude Desktop

Click the Claude (Heatwave) Dock tile, not the stock Claude.app
tile. The wrapper sets up env, then launches Claude Desktop. Quit any
running Claude.app first (⌘-Q) since macOS only allows one instance.

If the MCP server list still looks wrong, check bin/setup --doctor
output for hints, or re-run bin/setup --claude-app.

Available MCP Servers

PostgreSQL Databases

Server Database Access
postgres-dev Local Docker Read/Write
postgres-production Production heatwave READ-ONLY
postgres-replica Streaming replica READ-ONLY
postgres-versions Audit trail READ-ONLY

1Password Item: IT/heatwave-prod-db

See MCP_DATABASE_ACCESS.md for detailed usage.

Google Analytics

Access GA4 reporting data for all WarmlyYours properties.

Capabilities:

  • List accounts and properties
  • Run standard reports (traffic, conversions, etc.)
  • Run realtime reports
  • Get custom dimensions/metrics
  • List Google Ads links

1Password Item: IT/Google-Analytics-MCP

See Google Analytics Setup for first-time configuration.

AppSignal

Error tracking and application performance monitoring.

Capabilities:

  • View recent errors and exceptions
  • Check performance metrics
  • Monitor background jobs

1Password Item: IT/AppSignal-MCP

Other Servers

Server Purpose 1Password Item
keywordspeopleuse SEO keyword research IT/KeywordsPeopleUse API Key
svgmaker AI-powered SVG generation IT/SVGMaker
ahrefs SEO analytics and backlinks IT/Ahrefs-MCP
clarity-production Microsoft Clarity analytics IT/Clarity-MCP-Production
github GitHub repos, issues, PRs IT/GitHub-MCP-PAT

Google Analytics Setup

Google Analytics MCP requires a one-time GCP setup to create a service account. Once configured, the credentials are stored in 1Password for team-wide access.

For Team Members (Credentials Already in 1Password)

If IT/Google-Analytics-MCP already exists in 1Password:

eval $(op signin) && ./script/setup_mcp_servers.sh google-analytics

Restart Cursor. Done!

First-Time Setup (Create Service Account)

If you're the first person setting this up, follow these steps:

Step 1: Install Prerequisites

brew install pipx
pipx ensurepath
brew install --cask google-cloud-sdk

Step 2: Create GCP Project (or use existing)

# List existing projects
gcloud projects list

# Create new project (optional)
gcloud projects create google-analytics-mcp --name="Google Analytics MCP"

# Set as default
gcloud config set project YOUR_PROJECT_ID

Step 3: Enable Required APIs

gcloud services enable analyticsadmin.googleapis.com analyticsdata.googleapis.com

Step 4: Create Service Account

# Create service account
gcloud iam service-accounts create analytics-mcp \
  --display-name="Analytics MCP Service Account"

# Create and download key
gcloud iam service-accounts keys create ~/analytics-mcp-key.json \
  --iam-account=analytics-mcp@YOUR_PROJECT_ID.iam.gserviceaccount.com

Step 5: Grant Google Analytics Access

  1. Go to Google Analytics
  2. Click Admin (gear icon) → Account Access Management
  3. Click + → Add users
  4. Enter the service account email: 
    analytics-mcp@YOUR_PROJECT_ID.iam.gserviceaccount.com
  5. Select role: Viewer (or Marketer for more access)
  6. Click Add

Step 6: Store in 1Password

Create item in IT vault:

  1. Open 1Password app
  2. Create new API Credential item
  3. Title: Google-Analytics-MCP
  4. credential field: Paste entire contents of ~/analytics-mcp-key.json
  5. Add field project_id: Your GCP project ID
  6. Save

Or via CLI (if you have write access):

op item create \
  --category="API Credential" \
  --title="Google-Analytics-MCP" \
  --vault="IT" \
  "credential[text]=$(cat ~/analytics-mcp-key.json)" \
  "project_id[text]=YOUR_PROJECT_ID"

Step 7: Clean Up Local Key

rm ~/analytics-mcp-key.json

Step 8: Run Setup Script

eval $(op signin) && ./script/setup_mcp_servers.sh google-analytics

Restart Cursor.

Testing Google Analytics

After setup, ask the AI:

"What Google Analytics properties do I have access to?"
"Show me the top 10 pages on warmlyyours.com in the last 30 days"
"What are the traffic sources for the last week?"

Troubleshooting

"Not signed in to 1Password"

eval $(op signin)

MCP servers not loading in Cursor

  1. Ensure Docker Desktop is running
  2. Restart Cursor completely (Cmd+Q, reopen)
  3. Check config syntax: cat ~/.cursor/mcp.json | jq .

Google Analytics: "Permission denied"

The service account needs access to Google Analytics:

  1. Go to analytics.google.com → Admin
  2. Account Access Management → Add the service account email
  3. Grant at least Viewer role

Google Analytics: "pipx not found"

brew install pipx
pipx ensurepath
# Restart terminal

Docker containers piling up

MCP Docker containers may persist after Cursor closes:

./script/cleanup_mcp_docker.sh

Check current configuration

# User config (credentials)
cat ~/.cursor/mcp.json | jq .

# Project config (shared)
cat .cursor/mcp.json | jq .

Update credentials

Re-run the setup script:

eval $(op signin) && ./script/setup_mcp_servers.sh --all

Related Documentation

Changelog

December 2024

  • Added Google Analytics MCP with service account authentication
  • Added Claude Desktop configuration instructions
  • Consolidated MCP setup documentation