VibeMCP

Token-Optimized Unified MCP Server for Gmail & Microsoft 365

One server. Two ecosystems. Half the tokens.

Documentation · Getting Started · Tools Reference

---

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:

Dataset	TOON	JSON	Savings
Gmail - 10 messages	591	961	38%
Outlook - 10 messages	872	1,480	41%
Google Calendar - 11 events	441	1,462	70%
Combined	1,904	3,903	51%

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.

Cost impact at Claude Opus pricing ($15/M input tokens)

Usage	Annual Token Savings	Annual Cost Savings
10 calls/day	7.3M tokens	$109
50 calls/day	36.5M tokens	$547
200 calls/day	146M tokens	$2,190

---

Quick Start

1. Add to your MCP client

Claude Code (~/.claude.json):

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

2. Configure credentials

Pass credentials via your MCP client's env block:

{
  "mcpServers": {
    "vibemcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@vibetensor/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 @vibetensor/vibemcp auth google your@gmail.com
npx @vibetensor/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

31 tools across 5 categories:

Account Management (7)

Tool	Description
list_accounts	List all connected accounts with auth status
add_google_account	Start Google OAuth flow (browser-based)
complete_google_auth	Complete Google authentication
add_microsoft_account	Start Microsoft Device Code flow
complete_microsoft_auth	Complete Microsoft authentication
remove_account	Remove a connected account
accounts_status	Check auth status and server configuration

Gmail (8)

Tool	Description
gmail_list_messages	List/search messages with Gmail search operators
gmail_get_message	Get full message content with body and attachments
gmail_send_message	Send email with RFC 2822 compliance
gmail_reply_to_message	Reply with proper threading (In-Reply-To / References)
gmail_create_draft	Create a draft email
gmail_list_labels	List all Gmail labels
gmail_list_threads	List email threads
gmail_get_thread	Get full thread with all messages

Outlook (8)

Tool	Description
outlook_list_messages	List messages with folder filtering
outlook_get_message	Get full message content
outlook_send_message	Send email via Microsoft Graph
outlook_reply_to_message	Reply to a message
outlook_forward_message	Forward a message
outlook_list_folders	List mail folders
outlook_move_message	Move message between folders
outlook_search	Search messages via Microsoft Graph

Calendar (5)

Tool	Description
calendar_list_calendars	List calendars (Google or Outlook, auto-detected)
calendar_list_events	List events in a time range
calendar_create_event	Create event (supports Teams / Meet links)
calendar_update_event	Update an Outlook event
calendar_delete_event	Delete an event

Unified / Cross-Account (3)

Tool	Description
unified_search	Search across all email accounts simultaneously
unified_inbox	Aggregated unread messages from all accounts
unified_calendar	Merged calendar view across all providers

---

Comparison with Other MCP Servers

Feature	VibeMCP	gmail-mcp	ms-365-mcp-server	google_workspace_mcp
Gmail	8 tools	60+ tools	-	80+ tools
Outlook Mail	8 tools	-	90+ tools	-
Google Calendar	4 tools	-	-	included
Outlook Calendar	5 tools	-	included	-
Unified (both providers)	Yes	No	No	No
TOON output	Yes	No	No	No
Multi-account	Native	No	No	Manual
Cross-account search	Yes	No	No	No
Token optimization	51% avg	None	None	None

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)
    cache.ts              # Service instance cache (10-min TTL)
  tools/
    admin.ts              # Account management tools (7)
    gmail.ts              # Gmail tool handlers (8)
    outlook.ts            # Outlook tool handlers (8)
    calendar.ts           # Unified calendar tools (5)
    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 @vibetensor/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

Google OAuth 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)

Microsoft Auth Setup

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 (46 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 (Current)

• 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

• Attachment handling (upload / download)
• Google Calendar event update
• Gmail label management
• Test suite (TOON encoder, logger, token store, service cache)
• ESLint + Prettier configuration
• Docker support

v0.3 — Expand

• 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.

Guarantee	Detail
No telemetry	No analytics, no phone home, no data sent to VibeTensor or third parties
No hosted OAuth	You create your own Google Cloud project and Azure App Registration
Local token storage	OAuth tokens stored as local JSON files, never transmitted
No data retention	Passthrough only — fetches from APIs on demand, stores nothing
You own everything	Your credentials, your data, your infrastructure

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

---

Troubleshooting

Issue	Solution
"No accounts connected"	Run list_accounts to check. Authenticate at least one account.
Google OAuth fails	Ensure http://localhost:4100/code is an authorized redirect URI. Enable Gmail + Calendar APIs.
Microsoft device code expires	Codes last ~15 minutes. Run add_microsoft_account again for a fresh code.
AADSTS errors	Enable "Allow public client flows" in Azure Portal > App Registration > Authentication.
Token file issues	Delete ~/.vibemcp/.oauth2.{email}.json and re-authenticate.

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.

---

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.

---

Built by VibeTensor — a DPIIT-recognized AI startup from India
Website · GitHub · LinkedIn