VaultAssist - Personal Google Workspace MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Google Workspace integration for your personal AI assistant with vault-level security.

Built with Next.js, TypeScript, Better Auth, and Vercel's MCP SDK, this server enables natural language control over Gmail, Google Drive, Calendar, Sheets, Slides, and Tasks through secure OAuth 2.1 authentication with advanced session management and graph database integration.

Overview

VaultAssist acts as a secure bridge between AI assistants and Google Workspace services, enabling seamless automation and data access through a vault-secured, authenticated API. The server uses Better Auth for robust user session management, PostgreSQL for persistent data storage, and Graph DBs for intelligent relationship mapping across your personal data ecosystem. VaultAssist acts as a secure bridge between AI assistants and Google Workspace services, enabling seamless automation and data access through a vault-secured, authenticated API. The server supports multiple users, with each user's data, sessions, and Google Workspace access fully isolated. Better Auth provides robust user session management, PostgreSQL ensures persistent, per-user data storage, and Graph DBs enable intelligent, user-specific relationship mapping across your personal data ecosystem.

graph TB
    subgraph "Client Layer"
        VSCode[VS Code MCP Client]
        Other[Other MCP Clients]
    end

    subgraph "VaultAssist MCP Server (Next.js)"
        Auth[Better Auth<br/>OAuth 2.1 + MCP Plugin]
        Router[MCP Handler<br/>Vercel SDK + Dynamic Routes]
        
        subgraph "Tool Registry"
            Gmail[Gmail Tools]
            Drive[Drive Tools]
            Docs[Docs Tools]
            Calendar[Calendar Tools]
            Sheets[Sheets Tools]
            Slides[Slides Tools]
            Tasks[Tasks Tools]
            Memory[Memory Tools]
            Sequential[Sequential Thinking]
        end
        
        subgraph "Core Services"
            OAuth[Google OAuth Client]
            Schema[Zod Validation]
            DB[Database Layer]
            GraphDB[Graph Database<br/>Relationships & Context]
            SessionMgmt[Advanced Session<br/>Management]
        end
    end

    subgraph "Google APIs"
        GmailAPI[Gmail API]
        DriveAPI[Drive API]
        DocsAPI[Docs API]
        CalendarAPI[Calendar API]
        SheetsAPI[Sheets API]
        SlidesAPI[Slides API]
        TasksAPI[Tasks API]
    end

    subgraph "Infrastructure"
        PostgresDB[(PostgreSQL Database<br/>User Data & Sessions)]
        GraphStore[(Graph Database<br/>Relationships & Memory)]
        GoogleCloud[Google Cloud Console<br/>OAuth 2.1 Credentials]
        VercelSDK[Vercel MCP SDK<br/>& Libraries]
    end

    %% Client connections
    VSCode --> Router
    Other --> Router

    %% Authentication flow
    Router --> Auth
    Auth --> GoogleCloud
    Auth --> DB
    Auth --> SessionMgmt
    DB --> PostgresDB
    SessionMgmt --> GraphStore

    %% Tool registration and execution
    Router --> Gmail
    Router --> Drive
    Router --> Docs
    Router --> Calendar
    Router --> Sheets
    Router --> Slides
    Router --> Tasks
    Router --> Memory
    Router --> Sequential

    %% Service layer with MCP SDK integration
    Gmail --> OAuth
    Drive --> OAuth
    Docs --> OAuth
    Calendar --> OAuth
    Sheets --> OAuth
    Slides --> OAuth
    Tasks --> OAuth
    Memory --> GraphDB
    Sequential --> GraphDB

    %% External API calls
    OAuth --> GmailAPI
    OAuth --> DriveAPI
    OAuth --> DocsAPI
    OAuth --> CalendarAPI
    OAuth --> SheetsAPI
    OAuth --> SlidesAPI
    OAuth --> TasksAPI

    %% Data validation and MCP SDK
    Gmail --> Schema
    Drive --> Schema
    Docs --> Schema
    Calendar --> Schema
    Sheets --> Schema
    Slides --> Schema
    Tasks --> Schema
    Memory --> Schema
    Sequential --> Schema
    
    %% MCP SDK Integration
    Router --> VercelSDK
    Schema --> VercelSDK
    Auth --> VercelSDK

    %% Graph database relationships
    GraphDB --> PostgresDB
    GraphDB --> GraphStore

    %% Styling
    classDef clientNodes fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000000
    classDef serverNodes fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000000
    classDef apiNodes fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000000
    classDef infraNodes fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000000

    class VSCode,Other clientNodes
    class Auth,Router,Gmail,Drive,Docs,Calendar,Sheets,Slides,Tasks,Memory,Sequential,OAuth,Schema,DB,GraphDB,SessionMgmt serverNodes
    class GmailAPI,DriveAPI,DocsAPI,CalendarAPI,SheetsAPI,SlidesAPI,TasksAPI apiNodes
    class PostgresDB,GraphStore,GoogleCloud,VercelSDK infraNodes

Features

Secure

• OAuth 2.1 authentication with encrypted token storage

• Secure session management and automatic token refresh

• Input validation with Zod schemas and CORS protection

• Environment-based secrets management

• Multi-user isolation: Each user has a fully isolated workspace, with strict separation of sessions, tokens, and data. No cross-user access is possible. All Google Workspace API calls and memory graphs are partitioned per user for maximum privacy.

Google Workspace Coverage

• Gmail: Full email management with search, labels, and batch operations

• Drive: File operations with Office format support and URL imports

• Docs: Create, edit, search, and batch update Google Docs with advanced content manipulation

• Calendar: Event management with Google Meet and attachments

• Sheets: Spreadsheet operations with flexible data I/O

• Slides: Presentation management with batch updates

• Tasks: Complete task and task list management with hierarchy

Intelligent Context Management

• Graph database integration for relationship mapping across personal data

• Memory persistence for long-term context retention

• Sequential thinking patterns for complex task management

• Cross-platform data correlation and insights

Developer Experience

• Built on Vercel MCP SDK for optimal performance and reliability

• Full TypeScript implementation with Zod validation

• Modular architecture with clean separation of concerns

• PostgreSQL database with Drizzle ORM and graph database integration

• Support for multiple MCP transport methods such as Streamable HTTP & SSE (deprecated)

Architecture

Multi-User Architecture & Isolated Access

VaultAssist is designed for secure, multi-user operation. Each user authenticates via OAuth 2.1 and is assigned a unique, encrypted session. All Google Workspace API calls are performed strictly on behalf of the authenticated user, ensuring that:

• Data Isolation: User data, tokens, and memory graphs are partitioned and encrypted per user. No user can access another user's data or sessions.

• Session Security: Sessions are managed with Better Auth, providing advanced session isolation and automatic token refresh for each user.

• Per-User API Access: All Google API operations are scoped to the authenticated user's account, with no shared credentials.

• Database & Graph Partitioning: PostgreSQL and graph database entries are keyed and isolated per user, preventing cross-user data leakage.

This architecture enables VaultAssist to safely serve multiple users in parallel, with strong guarantees of privacy and access control.

Project Structure

mcp-server/
├── src/
│   ├── app/
│   │   ├── api/[transport]/     # MCP endpoint with tool registry
│   │   ├── auth/                # Authentication pages
│   │   └── dashboard/           # User dashboard
│   ├── lib/
│   │   ├── auth.ts              # Better Auth configuration
│   │   ├── db/                  # Database schema & operations
│   │   └── toolset/google/      # Google API implementations
│   └── components/              # UI components
├── drizzle/                     # Database migrations
└── package.json

Demo

https://github.com/user-attachments/assets/d0bf7f21-8044-4308-a029-1b8c13c439c9

Prerequisites

• Node v22+ and package manager (bun, npm etc.)

• PostgreSQL database (local or cloud)

• Neo4j database (Aura or self-hosted)

• Redis instance (Upstash or self-hosted)

• Google Cloud Project with OAuth 2.1 credentials

• MCP-compatible client (VS Code, etc.)

• Docker

Setup & Installation

1. Clone and Install Dependencies

git clone https://github.com/3xCaffeine/mcp-server.git
cd mcp-server
bun install # or npm install, pnpm install, yarn install

2. Database Setup

Set up your PostgreSQL database and configure environment variables:

# Copy environment template
cp .env.example .env

3. Google Cloud Console Setup

1. Create a Google Cloud Project

2. Enable APIs:

   • Gmail API

   • Google Drive API

   • Google Calendar API

   • Google Sheets API

   • Google Slides API

   • Google Tasks API

3. Create OAuth 2.1 Credentials:

   • Go to APIs & Services → Credentials

   • Click Create Credentials → OAuth Client ID

   • Choose Web Application

   • Add authorized redirect URIs:

     • http://localhost:3000/api/auth/callback/google

   • Download credentials and add to .env

4. Database Migration

# Generate and run migrations
bun run drizzle:generate
bun run drizzle:migrate

# Optional: Open Drizzle Studio to inspect database
bun run drizzle:studio

5. Development Server

# Start development server
bun dev

Visit http://localhost:3000/dashboard to access the web interface.

Deployment Steps

1. Check the Caddy config and start the services with Docker Compose.

cd mcp-server/deployment/
docker compose up -d

MCP Client Configuration

Open up the VS Code Command Palette > MCP:Open User Configuration and paste the below into mcp.json config.

VS Code MCP Client

{
	"servers": {
		"google-workspace": {
			"url": "https://mcp.rycerz.es:3000/api/mcp",
			"type": "http"
		}
	},
	"inputs": []
}

Authentication Flow

1. Initial Setup: User visits /auth and signs in with Google

2. OAuth Flow: Better Auth handles Google OAuth 2.1 flow with enhanced security

3. Token Storage: Access/refresh tokens stored securely in PostgreSQL with encryption

4. MCP Session: Better Auth MCP plugin manages session tokens with vault-level security

5. API Access: Each tool call uses stored tokens for Google API access

6. Graph Integration: User interactions are mapped to graph database for context management

Available Tools

Gmail Tools

Google Drive Tools

Google Docs Tools

Google Calendar Tools

Google Sheets Tools

Google Slides Tools

Google Tasks Tools

Memory Tools

Sequential Thinking Tools

Credits

• run-llama/mcp-nextjs - Next.js OAuth MCP implementation

• NapthaAI/http-oauth-mcp-server - MCP spec authorization extension

• GongRzhe/Gmail-MCP-Server - Gmail tools

• j3k0/mcp-google-workspace - Gmail & Calendar

• taylorwilsdon/google_workspace_mcp - Most of the google services were inspired by this

• modelcontextprotocol/servers - sequential thinking & knowledge graph based memory