G-Krusch MCP server
Commit Nov 11, 2026Connects AI agents to Google Workspace for RAG-based Drive search, document creation, Calendar management, and Gmail automation.
Also known as kruschdev/G-krusch
- Stars
- 0
- Tools
- 12
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- MIT
What is G-Krusch MCP?
G-Krusch connects AI agents to Google Workspace for RAG-based Drive search, document creation, Calendar management, and Gmail automation. It exposes 12 tools, such as get_agent_steering, search_drive_rag, read_drive_file.
Summary generated from the project's README
About G-Krusch MCP server
Connecting AI agents to your Google Workspace is what G-krusch enables for developers and autonomous coding agents. By bridging the gap between local IDE agents and cloud-based productivity tools, it allows agents to perform RAG-based searches across Google Drive, manage Google Calendar schedules, and automate Gmail communications. The server supports both SSE transport for web-based clients and stdio transport for local setups like Cursor or Claude Code.
Users can manage agent behavior through a cloud-synced agent.md file stored in Google Drive, which agents pull using the get_agent_steering tool. The system features a sophisticated three-tier RAG approach, combining semantic embeddings from local Ollama models or Gemini with SQLite FTS5 keyword search. It also provides specialized tools for creating native Google Docs, Sheets, and Slides directly from Markdown or CSV data. Setting up the server requires Google OAuth credentials and an optional Gemini API key.
What you can do with it
- 1Sync agent instructions via DriveUpdate your agent's persona and project rules from any device by editing a file in Google Drive.
- 2Perform hybrid document searchesSearch through your PDFs and Google Docs using both semantic meaning and specific keywords.
Written from the project's README. Every use case is checked against a quote from it.
G-Krusch MCP tools 12
Detected from the READMEget_agent_steeringsearch_drive_ragread_drive_filewrite_drive_filedelete_drive_filelist_drive_workspacesync_drive_ragget_workspace_statuslist_calendar_eventscreate_calendar_eventsearch_gmail_messagescompose_gmail_message
Automated checks
Ran Nov 15, 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 reachablekruschdev/g-krusch is public and reachablegithub.com/kruschdev/g-krusch ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/kruschdev/g-krusch ↗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 model12 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 GitHub🧠 Why G-Krusch?
Most AI agents are trapped either in ephemeral context windows or isolated local folders that you can't easily access when away from your workstation. G-Krusch bridges the gap between humans, coding agents, and personal assistants (krusch-companion) across your Google Workspace:
agent.mdCloud-Synced Steering: Edit your agent rules, project priorities, and personas from your phone, tablet, or web browser directly in Google Drive. When an agent boots, it dynamically pulls the latest instructions viaget_agent_steering(GET /api/steering).- Sovereign 1,024-Dim Vector & FTS5 BM25 Drive RAG: Queries your Google Docs, PDFs, notes, and specs using a 3-tier dense semantic embedding cascade (Tier 1: local GPU Ollama
snowflake-arctic-embed2:latest8K-ctx 1,024-dim -> Tier 2: Geminimodels/gemini-embedding-001atoutputDimensionality: 1024-> Tier 3: uncached deterministic 64-dim offline fallback) fused with SQLite FTS5 Porter-stemmed BM25 keyword search. - 3-Tier Page-Faithful PDF Extraction: Validates
%PDF-magic bytes prior to disk spooling (validatePdfMagicBytes) and extracts multi-page PDFs with page citations ([contract.pdf p.1]) via Tier 1 Krusch-Nexus (pdftotext -bbox-layout), Tier 2 system Popplerpdftotext, or Tier 3 pure-JS stream extraction (extractPdfTextNative). - Two-Way Agent Filesystem + Native Google Docs, Sheets & Slides: Agents can read project briefs from
context/, check decision logs inmemory/, and usewrite_drive_fileto create or update Markdown files, styled Google Docs (.gdoc), Google Sheets (.gsheetfrom CSV or Markdown tables), and 16:9 Google Slides presentations (.slidesfrom----separated Markdown decks) directly inoutput/. - Google Calendar & Gmail Extensions: Exposes hardened REST endpoints (
/api/calendar/events,/api/gmail/messages,/api/gmail/drafts,/api/gmail/send) so Krusch Companion can check your schedule, book appointments, search your inbox, and compose RFC-2822 / RFC-2047 emails.
📁 Workspace Structure in Google Drive
When G-Krusch connects to your Google Drive, it manages a dedicated workspace folder (defaults to G-Krusch):
Google Drive /
└── G-Krusch/
├── agent.md # Authoritative steering & invariants (edit anywhere)
├── context/ # Domain knowledge, architectural specs, SOPs
├── memory/ # Decisions, invariants, project logs
└── output/ # Agent-generated artifacts, reports, proposals
🛡️ Security & Concurrency Hardening
- AES-256-GCM Encrypted Token Vault (
src/lib/crypto.js&src/lib/db.js): OAuth 2.0 access and refresh tokens are encrypted at rest in SQLite WAL using AES-256-GCM with NIST SP 800-38D 12-byte (96-bit) IVs and 16-byte authentication tags (plus transparent legacy 16-byte IV decryption). - OAuth 2.0 CSRF State & CORS Origin Lockdown (
src/lib/oauth.js&src/lib/auth-guard.js): Generates one-time 32-byte CSRFstatetokens with constant-time validation on/auth/google/callback, and restricts browser CORS requests to trusted localhost, RFC1918 LAN, and Tailscale (100.64.0.0/10) origins. - FIFO Keyed Mutex & Atomic SQLite Transactions (
src/lib/mutex.js&src/lib/rag.js):AsyncKeyedMutexserializes concurrent OAuth token refreshes, workspace provisioning, per-path writes, and RAG indexing, whilesaveIndexedDocumentTransactionalcommits document chunks and FTS5 indices atomically with automatic FTS5 self-healing (ensureFtsSync). - Path Traversal, Drive Query Escaping & Workspace Boundary Guard (
src/lib/path-utils.js&src/lib/drive.js): Blocks.., control characters, and sensitive dotfiles (.env,.git,id_rsa,.pem), escapes backslashes and quotes in Drive API queries, and verifies workspace ancestry before trashing any file byfileId. - CRLF Header Injection Shield & RFC 2047 UTF-8 Encoder (
src/lib/extensions.js): Strips CR/LF and control characters from email headers, validates recipient addresses, and encodes non-ASCII subjects using=?UTF-8?B?...?=. - Constant-Time API Key Guard (
src/lib/auth-guard.js): Usescrypto.timingSafeEqualwhenAPI_KEYorGCRUSH_SECRETis configured to protect workspace and MCP endpoints against timing side-channel attacks, paired with HTML escaping (escapeHtml) on OAuth callback pages.
⚡ Quick Start & Diagnostics
1. Installation
git clone https://github.com/kruschdev/G-krusch.git
cd G-krusch
npm install
2. Configure Environment
Copy .env.example to .env and provide your Google OAuth credentials (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET) and optional GEMINI_API_KEY:
cp .env.example .env
3. Run Production Diagnostic Doctor & Tests
(All 32 unit & hardening tests run hermetically against an isolated per-PID temporary SQLite database with zero external credentials required)
# Run 12-point production diagnostic check (Node 22+, SQLite WAL + busy_timeout, FTS5 sync, 12-byte AES-256-GCM, OAuth, Embeddings, Nexus PDF, MCP, Extensions)
npm run doctor
# Run all 32 unit & hardening tests
npm test
4. Launch G-Krusch (CLI or Systemd User Service)
# Start directly on http://localhost:5446
npm start
# Or manage via systemd user service on port 5446
systemctl --user status g-krusch.service
systemctl --user restart g-krusch.service
Endpoints:
- Web Dashboard:
http://localhost:5446 - Health & Telemetry:
http://localhost:5446/api/health - MCP SSE Transport:
http://localhost:5446/mcp/sse - Google OAuth Flow:
http://localhost:5446/auth/google
🛠️ MCP Integration (Antigravity, Cursor, Claude Code)
SSE Transport (http://localhost:5446/mcp/sse)
{
"mcpServers": {
"g-krusch": {
"url": "http://localhost:5446/mcp/sse"
}
}
}
Stdio Transport
{
"mcpServers": {
"g-krusch": {
"command": "node",
"args": ["/absolute/path/to/G-krusch/src/index.js", "--stdio"]
}
}
}
🧰 Exposed MCP Tools (12 Tools)
| Tool | Description |
|---|---|
get_agent_steering |
Retrieves active agent.md steering directives directly from Google Drive. |
search_drive_rag |
Hybrid semantic vector + FTS5 BM25 keyword search across all indexed files in Google Drive. |
read_drive_file |
Reads any document from Drive (exports Google Docs, Sheets, Slides & PDFs cleanly to Markdown/CSV). |
write_drive_file |
Creates or updates Markdown files, native Google Docs (.gdoc), Google Sheets (.gsheet), or Google Slides presentations (.slides, with Notes: speaker notes) in the workspace. |
delete_drive_file |
Soft-trashes a file in the G-Krusch Google Drive workspace. |
list_drive_workspace |
Lists all folders and files in the G-Krusch Drive hierarchy. |
sync_drive_rag |
Triggers an incremental scan and embedding sync of Google Drive files. |
get_workspace_status |
Reports OAuth connection health, indexed file count, and cached embedding statistics. |
list_calendar_events |
Lists upcoming events from the user's primary Google Calendar with optional query and time window. |
create_calendar_event |
Schedules a new event or reservation hold on the user's primary Google Calendar. |
search_gmail_messages |
Searches Gmail messages using standard Gmail operators (is:unread, from:...). |
compose_gmail_message |
Creates an RFC-2822 / RFC-2047 sanitized Gmail draft or sends an email immediately (send_immediately: true). |
☁️ Google Workspace Extension REST APIs (Krusch Companion Bridge)
In addition to its MCP server, G-Krusch exposes REST Extension APIs on port 5446 consumed by krusch-companion's <holodata> Dual-Engine Agentic Proxy:
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/health |
Reports SQLite WAL health, OAuth status, Krusch-Nexus PDF engine status, RAG counts, and active extensions. |
GET |
/api/steering |
Retrieves agent.md cloud steering directives (?refresh=true to bypass cache). |
PUT |
/api/steering |
Updates agent.md steering content in Google Drive. |
GET |
/api/workspace/tree |
Returns recursive folder & file tree for the G-Krusch Google Drive workspace. |
GET |
/api/rag/search?q=... |
Hybrid semantic + FTS5 BM25 search across indexed Google Drive documents (gkrusch_drive). |
POST |
/api/rag/sync |
Incrementally indexes workspace documents into SQLite vector + FTS5 tables. |
GET |
/api/drive/read?path=... |
Reads a Google Drive file or exports a Google Doc, Sheet, Slides deck, or PDF (gkrusch_drive). |
POST |
/api/drive/write |
Creates or updates a Markdown file, native Google Doc (.gdoc), Google Sheet (.gsheet), or Google Slides deck (.slides) inside the G-Krusch Drive workspace (gkrusch_drive). |
DELETE |
/api/drive/file |
Soft-trashes a file by path or fileId. |
GET |
/api/calendar/events |
Lists upcoming events from the user's primary Google Calendar (gkrusch_calendar). |
POST |
/api/calendar/events |
Schedules a new Google Calendar event ({ summary, startTime, endTime, description }) (gkrusch_calendar). |
GET |
/api/gmail/messages?q=... |
Searches Gmail messages and returns sender, subject, date, and snippet previews (gkrusch_gmail). |
POST |
/api/gmail/drafts |
Encodes a CRLF-sanitized RFC-2822 / RFC-2047 MIME message and creates a Gmail draft (sendImmediately: false) or sends immediately (gkrusch_gmail / concierge_reservation). |
POST |
/api/gmail/send |
Sends a CRLF-sanitized RFC-2822 / RFC-2047 MIME email immediately via Gmail (sendImmediately: true). |
📄 License
MIT © kruschdev. Part of the Krusch Homelab Sovereign AI Ecosystem.
G-Krusch MCP questions
What tools does G-Krusch MCP provide?
It exposes 12 tools, including get_agent_steering, search_drive_rag, read_drive_file, write_drive_file, delete_drive_file.
How does G-Krusch handle document search?
It uses a hybrid RAG approach combining 1,024-dimensional semantic vector embeddings with SQLite FTS5 BM25 keyword search across Google Drive files.
How is my Google OAuth data secured?
OAuth 2.0 tokens are encrypted at rest in a SQLite database using AES-256-GCM with NIST-compliant IVs and authentication tags.
What is agent.md steering?
It allows you to manage agent rules and project priorities by editing an agent.md file in Google Drive, which the agent pulls dynamically upon booting.