Ziggy MCP

A Model Context Protocol (MCP) server that connects Claude AI to Google Sheets for automated revenue tracking, lead management, and business operations.

Features

• 📊 Dashboard: Real-time revenue metrics and KPIs

• 🎯 Lead Pipeline: Track prospects from first contact to close

• 📧 Gmail Integration: Search emails and automate outreach

• 📅 Calendar Sync: Track meetings and follow-ups

• 📝 Knowledge Matrix: Development log with timestamp tracking

• ✅ Task Management: Prioritize and track project tasks

• 📈 Analytics: Daily metrics and performance tracking

Related MCP server: Revenue Engine MCP

Prerequisites

• Node.js 18.0.0 or higher

• Google Account with Sheets and Gmail access

• Claude Desktop or compatible MCP client

• Google Apps Script (for backend API)

• Playwright (for browser automation)

Installation

1. Clone the Repository

git clone https://github.com/yourusername/ziggy-mcp.git
cd ziggy-mcp

2. Install Dependencies

npm run setup
# This installs Node packages AND Playwright browsers

Manual alternative:

npm install
npx playwright install chromium

3. Set Up Google Sheets Backend

1. Create a new Google Sheet

2. Go to Extensions > Apps Script

3. Delete any existing code

4. Copy all files from /apps-script directory:

   • Code.js - Sheet setup script

   • API.js - Main API handlers

   • calendarSync.js - Calendar integration

   • appsscript.json - Manifest

5. Click Save (disk icon)

6. Click Run > setupRevenueEngine

7. Authorize the script when prompted

8. Wait 30-60 seconds for completion

9. Deploy as web app:

   • Click Deploy > New deployment

   • Type: Web app

   • Execute as: Me

   • Who has access: Anyone

   • Click Deploy

   • Copy the Web app URL

4. Configure the MCP Server

Edit index.js and update the API URL:

const API_URL = "YOUR_GOOGLE_APPS_SCRIPT_WEB_APP_URL";

5. Connect to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ziggy": {
      "command": "node",
      "args": ["/absolute/path/to/ziggy-mcp/index.js"]
    }
  }
}

Replace /absolute/path/to/ziggy-mcp/ with your actual installation path.

6. Restart Claude Desktop

Quit and reopen Claude Desktop to load the MCP server.

Browser Automation Setup

Setting Up Authenticated Sessions

For Upwork, LinkedIn, and other platforms:

Step 1: Open browser in visible mode

Open Upwork in browser with visible mode

Step 2: I'll open a browser window - YOU log in manually

Step 3: Save the session

Save browser session as "upwork"

Step 4: Test it

Browse upwork.com using saved session

Supported Platforms

• ✅ Upwork - Job search, proposal submission

• ✅ LinkedIn - Profile research, connection requests

• ✅ Any website - Custom scraping and automation

Security Notes

• Sessions stored locally in sessions/ folder

• NEVER commit session files to git

• Sessions contain your auth tokens

• Expire after ~30 days

• Re-authenticate when needed

Usage

Basic Commands

Get Dashboard:

Show me my revenue dashboard

View Pipeline:

What leads are in my pipeline?

Add a Lead:

Add a new lead: Acme Corp, contact John Smith, email john@acme.com

Check Gmail:

Search my unread emails

Log Development Work:

Log to knowledge matrix: Fixed authentication bug in Gmail integration [45m]

Knowledge Matrix

The Knowledge Matrix is a structured development log that tracks:

• 🐛 Bugs & Fixes - Issues and resolutions

• ✨ Features Added - New functionality

• 🧪 Testing Results - Test outcomes

• 🎯 Decisions & Direction - Strategic choices

• 📚 Documentation Updates - Doc changes

• 🚀 Next Session Goals - Future work

Write Entry:

Write matrix entry for Bugs & Fixes: "3:45pm EST 🐛[BUG-001] Fixed Gmail auth timeout [30m]"

Query Matrix:

Search matrix for "authentication"

Daily Summary:

Generate matrix summary for today

Browser Automation

Take Screenshot:

Take a screenshot of competitor-site.com

Extract Data:

Extract pricing from acme.com/pricing

Fill Form:

Fill the contact form at example.com with lead data for John Doe

Research:

Browse to linkedin.com/company/acme and extract company info

Automated Outreach (after session setup):

Search Upwork for "web automation" jobs and show top 5

Project Structure

ziggy-mcp/
├── index.js                 # Main MCP server
├── package.json            # Node dependencies
├── browser/                # Browser automation
│   ├── playwright.js      # Core browser functions
│   ├── upwork.js          # Upwork automation
│   └── linkedin.js        # LinkedIn automation
├── apps-script/            # Google Apps Script files
│   ├── Code.js            # Sheet setup
│   ├── API.js             # API endpoints
│   ├── calendarSync.js    # Calendar integration
│   └── appsscript.json    # Manifest
├── sessions/               # Saved browser sessions (gitignored)
├── screenshots/            # Captured screenshots (gitignored)
├── docs/                   # Documentation
│   ├── MATRIX.md          # Knowledge Matrix guide
│   ├── BUG-TRACKING.md    # Bug tracking system
│   └── BROWSER-GUIDE.md   # Browser automation guide
└── README.md              # This file

Security & Privacy

• All data stored in your Google Sheets

• API calls authenticated through Google Apps Script

• No external databases or third-party services

• File system access restricted to project directory

• Gmail read-only access (send requires explicit approval)

Troubleshooting

MCP Server Not Connecting

1. Check Claude Desktop config path is correct

2. Verify Node.js version: node --version (should be ≥18.0.0)

3. Check console: Cmd+Shift+I in Claude Desktop

4. Verify API_URL is set correctly in index.js

Google Apps Script Issues

1. Ensure script is deployed as web app

2. Check execution permissions (should be "Anyone")

3. Re-authorize if needed: Run > setupRevenueEngine

4. Check Apps Script logs: View > Logs

Gmail Integration

1. Ensure Gmail API is enabled in Apps Script

2. Check OAuth scopes in appsscript.json

3. Re-authorize if permissions changed

Development

Running Locally

node index.js

Managing Apps Script

Install clasp for local Apps Script development:

npm install -g @google/clasp
clasp login
clasp pull  # Download from Google
clasp push  # Upload to Google

Debugging

Enable debug logging in index.js:

const DEBUG = true;

Logs written to debug.log in project directory.

Roadmap

• Add Slack integration

• Export reports to PDF

• AI-powered lead scoring

• Automated follow-up reminders

• Invoice generation

• Team collaboration features

Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Commit changes: git commit -m 'Add amazing feature'

4. Push to branch: git push origin feature/amazing-feature

5. Open a Pull Request

License

MIT License - see LICENSE file for details

Support

• 📧 Email: support@example.com

• 💬 Issues: GitHub Issues

• 📖 Docs: Wiki

Acknowledgments

• Built with Model Context Protocol

• Powered by Claude AI

• Google Sheets integration via Apps Script

Made with ❤️ for solopreneurs and small teams