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

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