MatthewCampCorp/stark-mcp

STARK Google Workspace MCP Server

A Model Context Protocol (MCP) server for interacting with Google Workspace services including Drive, Calendar, and Apps Script.

Features

• Drive Search: Search Google Drive for files and folders using the Drive API query syntax
• Calendar Quick Lookup: Retrieve upcoming calendar events from your primary calendar
• Apps Script Trigger: Execute custom Google Apps Script functions via Web App

Prerequisites

• Python 3.8 or higher
• Google Cloud Project with:
  • Drive API enabled
  • Calendar API enabled
  • Service account with domain-wide delegation configured
• (Optional) Deployed Google Apps Script Web App for custom functions

Installation

1. Clone or download this repository

2. Install dependencies:

pip install -r requirements.txt

3. Set up environment variables by copying .env.example to .env:

cp .env.example .env

4. Configure your .env file with:
   • GOOGLE_APPLICATION_CREDENTIALS: Path to your service account JSON key file
   • USER_EMAIL: Email address for domain-wide delegation
   • APPS_SCRIPT_URL: (Optional) Your deployed Apps Script Web App URL
   • APPS_SCRIPT_AUTH_TOKEN: (Optional) Authentication token for Apps Script

Service Account Setup

1. Create a service account in Google Cloud Console
2. Download the JSON key file
3. Enable domain-wide delegation for the service account
4. In Google Workspace Admin Console, authorize the service account with these scopes:
   • https://www.googleapis.com/auth/drive.readonly
   • https://www.googleapis.com/auth/calendar.readonly

Usage

Option 1: HTTP Gateway (Recommended for LLC Command Center)

For HTTP-based integrations like the LLC Command Center backend, use the HTTP gateway:

python http_gateway.py

The gateway runs on http://localhost:3000 and provides REST API endpoints. See HTTP_GATEWAY_README.md for full documentation.

Quick Start:

# Windows
start_gateway.bat

# Or manually
python http_gateway.py

Option 2: stdio MCP Server (For Claude Desktop)

Run the traditional stdio-based MCP server for Claude Desktop integration:

python -m server.server

The server communicates via stdio and can be integrated with MCP-compatible clients.

Tools

drive_search

Search Google Drive for files matching a query.

Parameters:

• query (string, required): Drive API search query
• max_results (integer, optional): Maximum results to return (1-100, default: 10)

Example queries:

• "name contains 'report'"
• "mimeType='application/pdf'"
• "modifiedTime > '2024-01-01'"

calendar_quick

Get upcoming calendar events.

Parameters:

• days_ahead (integer, optional): Number of days to look ahead (1-90, default: 7)

apps_script_trigger

Execute a Google Apps Script function.

Parameters:

• function_name (string, required): Name of the Apps Script function
• parameters (object, optional): Parameters to pass to the function

Project Structure

stark-mcp/
├── server/
│   ├── __init__.py
│   ├── server.py              # Main MCP server
│   ├── core/
│   │   ├── __init__.py
│   │   ├── auth.py            # Google authentication
│   │   └── apps_script_client.py  # Apps Script integration
│   └── tools/
│       ├── __init__.py
│       ├── drive_search.py    # Drive search tool
│       ├── calendar_quick.py  # Calendar tool
│       └── apps_script_trigger.py  # Apps Script tool
├── requirements.txt
├── .env.example
└── README.md

Error Handling

All tools include comprehensive error handling and will return descriptive error messages if:

• Authentication fails
• API calls fail
• Required environment variables are missing
• Invalid parameters are provided

License

This project is provided as-is for educational and development purposes.