Lets an AI client manage Gmail, Outlook, and calendars using a token-optimized format to reduce API costs and context usage.
Also known as VibeTensor/vibemcp
- Stars
- 5
- Tools
- 51
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- —
What is VibeMCP MCP?
VibeMCP lets an AI client manage Gmail, Outlook, and calendars using a token-optimized format to reduce API costs and context usage. It exposes 51 tools, such as list_accounts, add_google_account, complete_google_auth.
Summary generated from the project's README
About VibeMCP MCP server
Managing Gmail, Outlook, and calendars from within an AI client is what vibemcp enables through a unified interface. This server allows developers to interact with both Google and Microsoft ecosystems using a single set of tools. It is designed to reduce API costs and context window usage by employing Token-Oriented Object Notation (TOON), a format that replaces verbose JSON with tab-delimited rows to minimize token consumption.
Users set up the server locally via npx and configure it using environment variables for Google Client IDs and Microsoft Tenant IDs. Authentication is handled through browser-based OAuth for Google or a device code flow for Microsoft. The server provides 51 tools across modules for account management, email, calendars, and contacts. It even offers unified tools like unified_search and unified_calendar to aggregate data across all connected accounts simultaneously.
Written from the project's README. Every use case is checked against a quote from it.
VibeMCP MCP tools 51
Detected from the READMElist_accountsadd_google_accountcomplete_google_authadd_microsoft_accountcomplete_microsoft_authremove_accountaccounts_statusgmail_list_messagesgmail_get_messagegmail_send_messagegmail_reply_to_messagegmail_create_draft
Show all 51 toolsShow fewer tools
gmail_list_labelsgmail_list_threadsgmail_get_threadgmail_create_labelgmail_update_labelgmail_delete_labelgmail_modify_labelsgmail_download_attachmentgmail_batch_modifygmail_get_vacationgmail_set_vacationoutlook_list_messagesoutlook_get_messageoutlook_send_messageoutlook_reply_to_messageoutlook_forward_messageoutlook_list_foldersoutlook_move_messageoutlook_searchoutlook_list_categoriesoutlook_set_categoriesoutlook_set_flagoutlook_batch_updateoutlook_download_attachmentoutlook_list_attachmentsoutlook_get_auto_replyoutlook_set_auto_replycalendar_list_calendarscalendar_list_eventscalendar_create_eventcalendar_update_eventcalendar_delete_eventcalendar_free_busycontact_searchresolve_contactscontact_listunified_searchunified_inboxunified_calendar
Configuration
GOOGLE_CLIENT_IDGOOGLE_CLIENT_SECRETMICROSOFT_CLIENT_IDMICROSOFT_TENANT_ID
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablevibetensor/vibemcp is public and reachablegithub.com/vibetensor/vibemcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-13github.com/vibetensor/vibemcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model51 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubThe 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.
| 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
Release status (2026-10-30): The npm registry
still lists @vibetensor/vibemcp 0.2.0. The runtime dependency and Microsoft
authentication fixes merged on main await a new npm publication. For those
fixes, follow the from-source setup
at reviewed revision 6f59dbed5768bdaf098e18acadd9ad26c9a74ac8.
The npx examples below use the published package.
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
51 tools across 7 modules:
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 (16)
| 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 |
gmail_create_label |
Create a new Gmail label |
gmail_update_label |
Update label name or visibility settings |
gmail_delete_label |
Delete a user-created label |
gmail_modify_labels |
Add or remove labels from specific messages |
gmail_download_attachment |
Download an attachment with metadata |
gmail_batch_modify |
Batch archive, read, unread, trash, or untrash messages |
gmail_get_vacation |
Get current out-of-office auto-reply settings |
gmail_set_vacation |
Enable or disable out-of-office with date range |
Outlook (16)
| 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 |
outlook_list_categories |
List available Outlook categories |
outlook_set_categories |
Set categories on a message |
outlook_set_flag |
Set follow-up flag on a message |
outlook_batch_update |
Batch mark read/unread, archive, or move messages |
outlook_download_attachment |
Download an attachment by ID |
outlook_list_attachments |
List attachments on a message |
outlook_get_auto_reply |
Get current auto-reply (OOO) settings |
outlook_set_auto_reply |
Configure auto-reply with schedule |
Calendar (6)
| 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 with optional recurrence (RRULE) |
calendar_update_event |
Update an event (Google and Microsoft) |
calendar_delete_event |
Delete an event |
calendar_free_busy |
Check free/busy availability for calendars |
Contacts (3)
| Tool | Description |
|---|---|
contact_search |
Search contacts by name or email |
resolve_contacts |
Resolve email addresses to display names |
contact_list |
List contacts from a Google or Microsoft account |
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 | 16 tools | 60+ tools | - | 80+ tools |
| Outlook Mail | 16 tools | - | 90+ tools | - |
| Google Calendar | 6 tools | - | - | included |
| Outlook Calendar | 6 tools | - | included | - |
| Contacts | 3 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:
- No repeated keys - JSON repeats
"subject","from","date"for every item. TOON declares fields once in the header. - No syntax noise - No
{,},[,],",,characters consuming tokens. - Self-describing schema - The
[count]{fields}header tells the LLM what to expect, improving parsing accuracy. - 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 viaVIBEMCP_CONFIG_DIRenv var.- Default = MCP server - Running
vibemcp(ornpx @vibetensor/vibemcp) with no arguments starts the MCP stdio server. CLI subcommands (auth,accounts) handle setup. - stderr-safe logging -
console.logredirected toconsole.errorat 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
- Go to Google Cloud Console
- Create a new OAuth 2.0 Client ID (Desktop Application)
- Add
http://localhost:4100/codeas an authorized redirect URI - Enable the Gmail API and Google Calendar API
- 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)
- Go to Azure Portal > App Registrations
- Register a new application (any name)
- Set "Supported account types" to "Personal Microsoft accounts only" or "All account types"
- Under Authentication, enable "Allow public client flows" (required for Device Code)
- 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, GraphgetSchedule) - 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.
| 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.
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.
VibeMCP MCP questions
What tools does VibeMCP MCP provide?
It exposes 51 tools, including list_accounts, add_google_account, complete_google_auth, add_microsoft_account, complete_microsoft_auth.
Can I still get standard JSON output?
Yes, every tool in the server supports both TOON and standard JSON output via a format parameter.
What ecosystems does this server support?
The server provides unified access to both Google (Gmail/Calendar) and Microsoft (Outlook/Microsoft 365) ecosystems.