VibeMCP

The Problem

Most email and calendar MCP servers return verbose JSON that wastes tokens:

[
  {"id": "abc123", "subject": "Meeting Tomorrow", "from": "john@example.com", "date": "2025-12-18", "snippet": "Let's meet at 3pm..."},
  {"id": "def456", "subject": "Q4 Report", "from": "jane@example.com", "date": "2025-12-17", "snippet": "Please review the..."}
]

~85 tokens for 2 messages. Repeated keys ("id", "subject", "from", "date") eat tokens on every row.

The Solution

VibeMCP uses TOON (Token-Oriented Object Notation), an open format that declares the schema once, then streams data as tab-delimited rows:

messages[2]{id,subject,from,date,snippet}
abc123	Meeting Tomorrow	john@example.com	2025-12-18	Let's meet at 3pm...
def456	Q4 Report	jane@example.com	2025-12-17	Please review the...

~38 tokens for the same data. No repeated keys, no brackets, no quotes.

Every tool supports both toon and json output via the format parameter.

Benchmarks

Measured on live Gmail and Outlook accounts, February 2026:

Calendar events show 70% savings because the raw Google Calendar API response has deeply nested objects (start.dateTime, attendees[].email, organizer.email) that VibeMCP's service layer flattens to primitive values before TOON encoding.

Quick Start

1. Add to your MCP client

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "vibemcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vibemcp"]
    }
  }
}

2. Configure credentials

Pass credentials via your MCP client's env block:

{
  "mcpServers": {
    "vibemcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vibemcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-google-client-id",
        "GOOGLE_CLIENT_SECRET": "your-google-client-secret",
        "MICROSOFT_CLIENT_ID": "your-azure-client-id",
        "MICROSOFT_TENANT_ID": "common"
      }
    }
  }
}

Or create a .env file in your working directory or ~/.vibemcp/.env.

See the Configuration Guide for Google Cloud and Azure setup.

3. Authenticate

Through your AI assistant:

> Add my Google account     → opens browser for OAuth
> Add my Microsoft account  → prints device code for microsoft.com/devicelogin

Or via CLI:

npx vibemcp auth google your@gmail.com
npx vibemcp auth microsoft your@outlook.com

4. Use

> Show my latest emails

messages[10]{id,subject,from,date,snippet}
19485abc  Team standup notes  alice@company.com  2026-02-16  Here are the notes...
28ef9d01  Invoice #4521       billing@vendor.com 2026-02-15  Your invoice for...

Every tool supports format: "json" for standard JSON output.

Tools

51 tools across 7 modules:

Account Management (7)

Gmail (16)

Outlook (16)

Calendar (6)

Contacts (3)

Unified / Cross-Account (3)

Comparison with Other MCP Servers

Existing TOON MCP servers (like toon-mcp) are generic JSON-to-TOON converters. VibeMCP encodes at the source level, selecting optimal fields per data type.

TOON Format

TOON (Token-Oriented Object Notation) encodes structured data as a header + tab-delimited rows:

typeName[count]{field1,field2,field3}
value1a	value1b	value1c
value2a	value2b	value2c

• Header typeName[count]{fields} declares the schema once

• Rows are tab-separated values, one per line, no repeated keys

For single objects, TOON uses key-value format:

message:
  id: msg001
  subject: Meeting Tomorrow
  from: john@example.com

Why TOON beats JSON for LLMs:

1. No repeated keys - JSON repeats "subject", "from", "date" for every item. TOON declares fields once in the header.

2. No syntax noise - No {, }, [, ], ", , characters consuming tokens.

3. Self-describing schema - The [count]{fields} header tells the LLM what to expect, improving parsing accuracy.

4. JSON fallback - Every tool accepts format: "json" for debugging or downstream processing.

See TOON.md for detailed documentation on nested object handling, schema evolution, and MCP client compatibility.

Architecture

src/
  index.ts                # MCP server entry point (StdioServerTransport)
  cli.ts                  # CLI for auth management
  config.ts               # Environment, account registry, scopes
  auth/
    google.ts             # Google OAuth2 with local callback server (port 4100)
    microsoft.ts          # Microsoft MSAL Device Code Flow
    store.ts              # Token file I/O helpers
  services/
    gmail.ts              # Gmail API service (googleapis)
    ms-mail.ts            # Microsoft Graph Mail (native fetch)
    google-calendar.ts    # Google Calendar API service
    ms-calendar.ts        # Microsoft Graph Calendar (native fetch)
    google-contacts.ts    # Google People API for contact resolution
    ms-contacts.ts        # Microsoft Graph People/Contacts
    cache.ts              # Service instance cache (10-min TTL)
  tools/
    admin.ts              # Account management tools (7)
    gmail.ts              # Gmail tool handlers (16)
    outlook.ts            # Outlook tool handlers (16)
    calendar.ts           # Unified calendar tools (6)
    contacts.ts           # Contact search and resolution (3)
    unified.ts            # Cross-account aggregation (3)
  toon/
    encoder.ts            # TOON serialization (encodeToon, formatOutput)
    types.ts              # ToonOptions interface
  utils/
    logger.ts             # stderr-safe logging (protects JSON-RPC stdout)
    errors.ts             # Error categories and formatting

Key design decisions:

• ~/.vibemcp/ config directory - Tokens, accounts, and MSAL cache stored in a persistent user directory (~/.vibemcp/), not relative to the package install location. Overridable via VIBEMCP_CONFIG_DIR env var.

• Default = MCP server - Running vibemcp (or npx vibemcp) with no arguments starts the MCP stdio server. CLI subcommands (auth, accounts) handle setup.

• stderr-safe logging - console.log redirected to console.error at import time, keeping stdout clean for MCP JSON-RPC

• Static factory pattern - Services use ServiceClass.create(email) because auth initialization is async

• Provider auto-detection - Calendar tools check the account registry to route to the correct service

• Service cache (10-min TTL) - Authenticated instances are cached to avoid repeated token acquisition

Auth Setup

1. Go to Google Cloud Console

2. Create a new OAuth 2.0 Client ID (Desktop Application)

3. Add http://localhost:4100/code as an authorized redirect URI

4. Enable the Gmail API and Google Calendar API

5. Copy the Client ID and Client Secret to your .env

Scopes requested:

• openid + userinfo.email (identity)

• https://mail.google.com/ (full Gmail access)

• https://www.googleapis.com/auth/calendar (Calendar read/write)

1. Go to Azure Portal > App Registrations

2. Register a new application (any name)

3. Set "Supported account types" to "Personal Microsoft accounts only" or "All account types"

4. Under Authentication, enable "Allow public client flows" (required for Device Code)

5. Copy the Application (client) ID to your .env

Scopes requested:

• Mail.ReadWrite, Mail.Send (email)

• Calendars.ReadWrite (calendar)

• User.Read (profile)

Personal accounts (hotmail/outlook/live) automatically exclude Teams scopes.

Development

npm install          # Install dependencies
npx tsc --noEmit     # Type check
npm run build        # Build
npm run dev          # Dev mode (auto-reload)
npm test             # Run tests (149 tests)
npm run lint         # ESLint check
npm run format       # Prettier format
node dist/index.js   # Run directly

Docker

docker build -t vibemcp .
docker run --env-file .env vibemcp

Roadmap

v0.1 - Foundation

• Gmail (8 tools) with TOON output

• Outlook Mail (8 tools) with TOON output

• Google Calendar (4 tools)

• Outlook Calendar (5 tools)

• Multi-account authentication (Google OAuth + Microsoft Device Code)

• Unified cross-account tools (search, inbox, calendar)

• CLI for account management

• Published on npm

v0.2 - Polish (Current)

• Attachment handling (download for Gmail and Outlook)

• Google Calendar event update

• Gmail label management (create, update, delete, apply to messages)

• Email batch operations (archive, mark read/unread, trash for Gmail; mark read/unread, archive, move for Outlook)

• Outlook categories and follow-up flags

• Test suite (149 tests across 8 suites)

• ESLint + Prettier configuration

• Docker support

v0.3 - Expand (Current)

• Contact name resolution via Google People API and Microsoft Graph

• Calendar free/busy lookup (Google freebusy.query, Graph getSchedule)

• Recurring event support (RRULE patterns for create)

• Out-of-office and auto-reply status (Gmail vacation, Outlook auto-reply)

• Slack integration

• Todoist integration

• Semantic caching layer

• Rate limiting

v1.0 - Production

• Hosted OAuth (no user GCP / Azure setup needed)

• Teams chat integration

• Google Drive / OneDrive

• Enterprise SSO

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

High-priority areas:

• Unit and integration tests

• New service modules (Slack, Todoist, Discord)

• TOON encoder improvements

• Documentation and usage examples

Privacy & Security

VibeMCP is fully self-hosted. Your data never leaves your machine.

See PRIVACY.md for full details and SECURITY.md for security policy.

Troubleshooting

Full troubleshooting guide: vibemcp.vibetensor.com/guide/getting-started

References

• MCP Specification - Model Context Protocol

• TOON Format - Token-Oriented Object Notation (v3.0)

• MCP Security Best Practices

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Google or Microsoft.

Gmail, Google Calendar, and Google Cloud are trademarks of Google LLC. Microsoft 365, Outlook, Azure, and Microsoft Graph are trademarks of Microsoft Corporation. VibeMCP uses these services' public APIs under their respective Terms of Service.

Users are responsible for creating their own API credentials and complying with Google APIs ToS, Google API User Data Policy, and Microsoft APIs ToU.

Sponsors

VibeMCP is free for personal use. If you or your organization benefit from it, please consider sponsoring to support continued development.

License

PolyForm Noncommercial 1.0.0 - VibeTensor Private Limited

Free for personal use, research, education, hobby projects, and noncommercial organizations. Commercial use requires a separate license from VibeTensor.