OpenWorkspace

Zero-dependency TypeScript toolkit for Google Workspace -- CLI, programmatic API, and MCP Server in one monorepo.

OpenWorkspace (@openworkspace/*) provides type-safe access to 15 Google Workspace services through three interfaces: a programmatic TypeScript API, a zero-dependency CLI (ows), and a Model Context Protocol (MCP) server with 28 tools for AI assistants.

npm install @openworkspace/core @openworkspace/gmail

Features

Zero external dependencies -- only workspace cross-references between packages
Type-safe Result pattern -- every function returns Result<T, E>, never throws
15 Google Workspace services -- Gmail, Calendar, Drive, Sheets, Docs, Slides, Contacts, Tasks, Chat, Classroom, Forms, Apps Script, People, Groups, Keep
CLI with 19 command groups -- ows gmail search, ows calendar events, ows drive upload, ...
MCP Server with 28 tools -- connect to Claude Desktop, Cursor, or any MCP-compatible client
YAML pipeline engine -- orchestrate multi-step workflows with expressions, forEach, parallel, and retries
Micro-kernel plugin architecture -- each service is a standalone, independently installable package
ESM-only, TypeScript strict mode -- modern, tree-shakeable modules
Node.js >= 22 -- leverages native fetch, crypto, and other built-in APIs
2,356 tests, 100% statement coverage -- across all 19 packages

Quick Start

Install

# Install individual packages as needed
npm install @openworkspace/core @openworkspace/gmail

# Or install the CLI globally
npm install -g @openworkspace/cli

Programmatic API

import { createHttpClient } from '@openworkspace/core';
import { searchMessages } from '@openworkspace/gmail';

const http = createHttpClient({
  baseUrl: 'https://www.googleapis.com',
  auth: { accessToken: 'your-token' },
});

const result = await searchMessages(http, { query: 'from:boss' });

if (result.ok) {
  console.log(result.value.messages);
} else {
  console.error(result.error.message);
}

CLI

# Authenticate
ows auth add ersin@example.com

# Gmail
ows gmail search "from:boss"
ows gmail send --to alice@example.com --subject "Hello"

# Calendar
ows calendar events --today
ows calendar create "Team Standup" --date 2026-03-15 --time 09:00

# Drive
ows drive search "quarterly report"
ows drive upload ./report.pdf

# Start MCP server
ows mcp serve --stdio

MCP Server (Claude Desktop)

Add to your Claude Desktop configuration:

// ~/.config/claude/claude_desktop_config.json
{
  "mcpServers": {
    "openworkspace": {
      "command": "npx",
      "args": ["@openworkspace/mcp", "serve", "--stdio"]
    }
  }
}

Once configured, Claude can search your email, create calendar events, upload files to Drive, and more -- all through natural language.

Pipeline

Define multi-step workflows in YAML:

name: Daily Backup
steps:
  - id: search
    action: gmail.search
    with:
      query: "has:attachment newer_than:1d"

  - id: upload
    action: drive.upload
    forEach: ${{ steps.search.result }}
    with:
      folderId: "backup-folder-id"

Pipelines support ${{ expr }} expressions, forEach iteration, parallel execution, and automatic retries.

Packages

Package	Description
`@openworkspace/core`	Kernel, Result type, errors, events, logger, HTTP client, auth (OAuth2, service accounts), config
`@openworkspace/cli`	Zero-dep CLI parser with 19 command groups, output formatters, shell completions
`@openworkspace/mcp`	MCP server -- JSON-RPC 2.0, 28 tools, stdio + HTTP/SSE transports
`@openworkspace/pipeline`	YAML workflow engine -- expression evaluator, forEach, parallel, retries
`@openworkspace/gmail`	Gmail -- search, read, send, labels, threads, drafts
`@openworkspace/calendar`	Calendar -- events, create, free/busy, calendar list
`@openworkspace/drive`	Drive -- search, upload, download, folders, permissions
`@openworkspace/sheets`	Sheets -- read, write, append, format, structure
`@openworkspace/docs`	Docs -- get, create, batch update, export
`@openworkspace/slides`	Slides -- presentations, slide ops, speaker notes, export
`@openworkspace/contacts`	Contacts -- search, list, create, directory
`@openworkspace/tasks`	Tasks -- task lists, tasks CRUD
`@openworkspace/chat`	Chat -- spaces, messages, direct messages
`@openworkspace/classroom`	Classroom -- courses, coursework, roster, submissions
`@openworkspace/forms`	Forms -- get, create, responses
`@openworkspace/appscript`	Apps Script -- run scripts, manage projects
`@openworkspace/people`	People -- profiles, manager/reports relations
`@openworkspace/groups`	Groups -- list, members, settings
`@openworkspace/keep`	Keep -- notes, attachments

Architecture

                        +-------------------+
                        |   @openworkspace  |
                        |      /core        |
                        |  (micro-kernel)   |
                        +--------+----------+
                                 |
            +--------------------+--------------------+
            |                    |                    |
   +--------v--------+  +-------v--------+  +--------v--------+
   |   @openworkspace |  | @openworkspace |  | @openworkspace  |
   |      /cli        |  |     /mcp       |  |   /pipeline     |
   |  (19 commands)   |  | (28 tools)     |  | (YAML engine)   |
   +--------+---------+  +-------+--------+  +--------+--------+
            |                     |                    |
            +--------------------+--------------------+
            |         Service Plugins (15)             |
            +------------------------------------------+
            | gmail | calendar | drive | sheets | docs |
            | slides | contacts | tasks | chat | ...  |
            +------------------------------------------+

Core Concepts

Result Pattern -- All functions return Result<T, E> instead of throwing:

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

Plugin Architecture -- Each service registers as a plugin with the kernel. Install only what you need.

HttpClient -- Authenticated HTTP with request/response/error interceptors, built on native fetch.

MCP Tools

The MCP server exposes 28 tools to AI assistants:

Tool	Description
`gmail_search`	Search messages by query
`gmail_read`	Read a specific message
`gmail_send`	Send an email
`gmail_labels`	List Gmail labels
`calendar_events`	List calendar events
`calendar_create`	Create a calendar event
`calendar_freebusy`	Check free/busy status
`drive_search`	Search files in Drive
`drive_read`	Read file content or metadata
`drive_upload`	Upload a file to Drive
`sheets_read`	Read spreadsheet data
`sheets_write`	Write spreadsheet data
`tasks_list`	List task lists and tasks
`tasks_create`	Create a new task
`tasks_complete`	Mark a task as complete
`contacts_search`	Search contacts
`docs_get`	Get document content
`docs_create`	Create a new document
`slides_get`	Get presentation content
`slides_create`	Create a new presentation
`classroom_courses`	List courses
`forms_get`	Get form and responses
`chat_send`	Send a chat message
`keep_list`	List notes
`appscript_run`	Run an Apps Script function
`people_me`	Get current user profile
`groups_list`	List groups
`workspace_search`	Search across all services

Development

Prerequisites

Node.js >= 22
pnpm >= 10

Setup

git clone https://github.com/ersinkoc/openworkspace.git
cd openworkspace
pnpm install

Build

pnpm build          # Build all packages (topological order via Turbo)

Testing

pnpm test           # Run all 2,356 tests
pnpm test:coverage  # Run tests with coverage (100% statement coverage)
pnpm typecheck      # TypeScript strict mode check

Manual Testing with Real Google Account

pnpm quickstart     # Interactive setup wizard for Google OAuth
pnpm smoke-test     # Run CLI commands against a real Google account
pnpm test:mcp       # Test MCP server via stdio JSON-RPC
pnpm test:e2e       # Full E2E test across all 15 services

See scripts/README.md for prerequisites and detailed setup instructions.

Project Structure

openworkspace/
  packages/
    core/          # Kernel, Result, errors, events, logger, HTTP, auth, config
    cli/           # CLI parser and command handlers
    mcp/           # MCP server, JSON-RPC 2.0, tool registry, transports
    pipeline/      # YAML workflow engine, expression evaluator
    gmail/         # Gmail service plugin
    calendar/      # Calendar service plugin
    drive/         # Drive service plugin
    sheets/        # Sheets service plugin
    docs/          # Docs service plugin
    slides/        # Slides service plugin
    contacts/      # Contacts service plugin
    tasks/         # Tasks service plugin
    chat/          # Chat service plugin
    classroom/     # Classroom service plugin
    forms/         # Forms service plugin
    appscript/     # Apps Script service plugin
    people/        # People service plugin
    groups/        # Groups service plugin
    keep/          # Keep service plugin
  scripts/         # Quickstart, smoke test, MCP test scripts
  docs/            # Architecture, specification, roadmap
  turbo.json
  pnpm-workspace.yaml
  tsconfig.json

Authentication

OpenWorkspace supports two authentication methods:

OAuth 2.0 (User Accounts)

# Browser flow (default -- opens browser for consent)
ows auth add ersin@example.com

# Headless flow (for servers -- paste the authorization code)
ows auth add ersin@example.com --headless

# Device code flow (for constrained devices)
ows auth add ersin@example.com --device

# Limit scopes to specific services
ows auth add ersin@example.com --scopes gmail,calendar,drive

Tokens are encrypted and stored locally. Auto-refresh is handled transparently.

Service Accounts

import { createServiceAccountAuth, loadServiceAccountKey } from '@openworkspace/core';

const key = await loadServiceAccountKey('./service-account.json');
const auth = createServiceAccountAuth(key);

Documentation

Architecture -- design decisions and package structure
Specification -- project spec and constraints
Roadmap -- milestones and task tracking
Scripts Guide -- manual testing setup

License

MIT -- Ersin Koc

@openworkspace/mcp

Quick Install