Skip to content
Back to search

modular-context-obsidian-plugin

Modular Context | Karpathy LLM Knowledge Base + Gmail & G-Cal — multi-account MCP server for Claude Code, encrypted local-first

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/klemensgc--modular-context-obsidian-plugin/badge.svg)](/listings/klemensgc--modular-context-obsidian-plugin)

HTML

<a href="/listings/klemensgc--modular-context-obsidian-plugin"><img src="/api/listings/klemensgc--modular-context-obsidian-plugin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Plugin

Requires Obsidian ≥ 0.15 and macOS (Linux + Windows may work; untested).

**Via BRAT (Beta Reviewer plugin, recommended for now):** 1. Install BRAT from Community Plugins 2. `Cmd+P` → "BRAT: Add a beta plugin" → `klemensgc/modular-context-obsidian-plugin` 3. Enable in Settings → Community plugins

**Manual:** 1. Download `main.js`, `manifest.json`, `styles.css`, `mcp-server.js` from [latest release](https://github.com/klemensgc/modular-context-obsidian-plugin/releases) 2. Copy to `<vault>/.obsidian/plugins/modular-context/` 3. Enable plugin in Settings → Community plugins → Modular Context

MCP server

**Auto-installed** on first `Google Workspace: Connect`. Plugin copies bundled binary to `~/.modular-context/mcp-google/dist/index.js` (~100 MB one-time).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 340 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Modular Context | Obsidian LLM Knowledge Base for Strategy, Ops & Comms
  2. ![banner](banner.png)
  3. > *Your Obsidian vault as LLM-native knowledge base + multi-account Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, Slides) exposed as 25 MCP tools for Claude Code. Local-first, encrypted, no telemetry.*
  4. ![Version](https://img.shields.io/github/v/release/klemensgc/modular-context-obsidian-plugin)
  5. ![License](https://img.shields.io/github/license/klemensgc/modular-context-obsidian-plugin)
  6. ![Platform](https://img.shields.io/badge/platform-macOS-blue)
  7. ![Obsidian](https://img.shields.io/badge/Obsidian-0.15+-purple)
  8. ---
  9. ## What is this?
  10. **Two things in one plugin:**
  11. 1. **LLM Knowledge Base** — Your Obsidian vault structured as Sources → Wiki → Schema (Karpathy-aligned framing). Multi-terminal Claude Code + Codex with skills sidebar, agent tracking, session glyphs. Your second brain seen by LLMs as a first-class context.
  12. 2. **G-Suite MCP Server** — Multi-account Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, Slides) exposed as 25 native tools for Claude Code (`gmail_search`, `drive_list_files`, `docs_create_doc`, `sheets_append_row`, `slides_read_presentation`, …). OAuth 2.0 + PKCE desktop flow, tokens encrypted via Electron `safeStorage` (OS keychain), no telemetry, no cloud.
  13. One install, one onboarding, two productivity frontiers.
  14. ---
  15. ## 🏢 The AI Company Stack
  16. The plugin isn't just a terminal + an MCP server — paired with the [skills library](https://github.com/klemensgc/modular-context-skills) it's a **whole AI company stack** running on one workflow: your vault is the brain, Claude Code is the operator, and each layer plugs into the next.
  17. | Layer | What it does | Skills |
  18. |-------|--------------|--------|
  19. | 🎙️ **Notetaker** | Turn raw transcripts, calls and tweets into structured, tagged knowledge | `process-transcripts`, `xdaily`, `graduate` |
  20. | 🧠 **Self-healing Knowledge Base** | The vault keeps itself current — reweaves stale modules, fixes links, audits structure, syncs sibling vaults | `reweave`, `vault-audit`, `graph`, `sync`, `pulse` |
  21. | 📡 **Communication layer** | One read across mail, WhatsApp and Google Workspace — what's happening and what belongs to you | `comms-review`, `whatsapp-digest`, `gsuite-analysis` |
  22. | 📊 **CRM / ops** | Ready skills that connect to ClickUp — review your sales funnel and pull your weekly plan straight from the workspace | `clickup-review`, `review-core`, `tasklist` |
  23. Each layer is independently useful; together they run a one-person company on autopilot. Skills install from the in-app library (dependencies auto-resolve).
  24. ---
  25. ## Architecture
  26. ```
  27. ┌──────────────────────────────────────────────────────────────────┐
  28. │ YOUR VAULT — your full context, structured so an LLM works on │
  29. │ YOUR reality: projects · people · decisions · history │
  30. │ │
  31. │ Sources → Wiki → Schema │
  32. │ raw input linked notes structured & typed (LLM-navigable) │
  33. └──────────────────────▲────────────────────────▲───────────────────┘
  34. reads │ │ writes back
  35. ╔═══════════════════════╧════════════════════════╧═══════════════════╗
  36. ║ 🦀 CLAUDE CODE (the operator) 🦀 ║
  37. ║ ║
  38. ║ ── works on your notes ── ── works with the world ── ║
  39. ║ 🦀 Capture 🦀 Keep current 🦀 Communicate 🦀 Operate ║
  40. ║ calls & files fix outdated read & send review & ║
  41. ║ → notes notes + links email·WhatsApp act (CRM) ║
  42. ╚══════════════════════════════════════════╦═════════════════╦═══════╝
  43. ▼ ▼
  44. COMMUNICATIONS (read + send)
  45. ├─ Gmail ← search → send / draft / labels
  46. └─ WhatsApp ← read messages (read-only · macOS)
  47. OPERATIONS (read + write)
  48. └─ ClickUp ← sales funnel · your tasks · weekly plan → update · batch actions
  49. WORKSPACE (Google · multi-account)
  50. ├─ Calendar ← list → create / update / delete
  51. ├─ Drive ← list / search → download / upload
  52. ├─ Docs ← read → create / update
  53. ├─ Sheets ← read → write / append
  54. └─ Slides ← read → create / add slide
  55. ── set up by ──▶ Modular Context Plugin (installs skills · handles Google login)
  56. ```
  57. **Architecture decisions** ([full ADRs in `docs/adrs/`](docs/adrs/)):
  58. - [ADR-001](docs/adrs/ADR-001-oauth-strategy.md) — Hybrid OAuth: Quick Connect (shared client) + BYO (user-provided client)
  59. - [ADR-002](docs/adrs/ADR-002-token-storage.md) — Electron `safeStorage` token storage (OS keychain)
  60. - [ADR-003](docs/adrs/ADR-003-mcp-server-lifecycle.md) + [addendum](docs/adrs/ADR-003-addendum-shared-state.md) — MCP server stdio lifecycle + plaintext credentials sidecar
  61. - [ADR-005](docs/adrs/ADR-005-multi-account-storage.md) — Multi-account storage model (per-account folder + index)
  62. ---
  63. ## Features
  64. ### LLM Knowledge Base
  65. - **Multi-terminal split layouts** — single, side-by-side, stacked, 2×2, 2×3, 2×4. Up to 8 sessions.
  66. - **Claude Code + Codex** — toggle AI provider in settings; auto-launch on new terminal.
  67. - **Skills sidebar** — 3 primary skills (full-width), rest in secondary grid. One-click launches.
  68. - **Agent tracker** — Working / To Review / Standby states per session.
  69. - **Session glyphs** — unique geometric shape per terminal. Skills inherit their icon.
  70. - **Compact mode** — 48px icon-only sidebar, maximum terminal real estate.
  71. - **Fullscreen overlay** — terminal fills Obsidian; sidebar docks right. `Esc` to exit.
  72. - **Real PTY** — zsh in a pseudo-terminal, not a basic runner.
  73. - **Wiki-link autocomplete** — `[[` inside terminal searches vault notes.
  74. - **Drag-and-drop** — Finder / Obsidian → terminal as shell-escaped paths.
  75. - **Session persistence** — tab names, glyphs, layouts survive restarts.
  76. - **Smart Session Restore** — on reopen, picker modal classifies saved sessions (Needs attention / Idle / Archive) instead of silent auto-resume. You choose what materializes — no accidental skill re-runs.
  77. - **Auto-onboarding** — first install triggers a setup agent that scaffolds your vault.
  78. ### G-Suite MCP Server (v2.1 — 25 tools)
  79. - **Multi-account** — unlimited Google accounts in parallel (Testing mode: up to 100 test users per account)
  80. - **25 tools** for Claude Code across 6 Workspace products (Gmail ×4, Calendar ×6, Drive ×4, Docs ×3, Sheets ×5, Slides ×3 — see table below)
  81. - **Zero telemetry** — no metrics, no crash reports, no external calls beyond OAuth + Google API
  82. - **Local-first** — tokens encrypted via OS keychain (macOS Keychain / Windows DPAPI / Linux libsecret via `libsecret`)
  83. - **Auto-refresh** — 50-minute timer per account, 5-minute expiry buffer
  84. - **Error taxonomy** — `TOKEN_EXPIRED`, `ACCOUNT_NOT_FOUND`, `SCOPE_OUTDATED`, `RATE_LIMITED`, `PERMISSION_DENIED`, `QUOTA_EXCEEDED`, `NETWORK_ERROR`
  85. - **Hot reload** — server re-reads credentials per tool call, zero-downtime refresh
  86. ---
  87. ## 3 primary skills (post-onboarding)
  88. | Skill | Purpose | Uses |
  89. |-------|---------|------|
  90. | **Synthesise Files** | Turn raw files (transcripts, notes, backlog) into vault modules — categorize, tag, update, reweave neighbors | Your vault, optional `_transcripts-backlog/` |
  91. | **WhatsApp Digest** | Analyze WhatsApp groups for action items, blindspots, staleness vs vault | macOS WhatsApp.app |
  92. | **Gmail + G-Suite** | Inbox sweep, stale follow-ups, calendar gap analysis, meeting prep, doc extraction, sheet logging, deck prep | MCP tools below |
  93. All three write artifacts to `_workspace/{YYYY-MM}/w{N}/`. Secondary skills (Pulse, Brief, Log, Reweave, Graph, Graduate, Ideas, Vault-Audit) available in sidebar grid.
  94. ---
  95. ## 25 MCP tools
  96. ### Gmail (4)
  97. | Tool | Purpose |
  98. |------|---------|
  99. | `gmail_search` | Query with Gmail syntax (`is:unread`, `from:X`, `after:2026-04-01`). Optional body extraction. |
  100. | `gmail_draft` | Create draft — not sent. User opens `webUrl` in Gmail UI to send. |
  101. | `gmail_send` | Send immediately. Skip draft for trusted, scripted sends. |
  102. | `gmail_modify_labels` | Add/remove labels — system presets (`INBOX`, `UNREAD`, `STARRED`, `IMPORTANT`, `SPAM`, `TRASH`) + custom labels by name. |
  103. ### Calendar (6)
  104. | Tool | Purpose |
  105. |------|---------|
  106. | `calendar_list_calendars` | Enumerate all calendars user has access to. |
  107. | `calendar_list_events` | Events in time range. |
  108. | `calendar_create_event` | Create event (`sendUpdates: "none"` default — no auto-invite spam). |
  109. | `calendar_update_event` | Patch existing (only provided fields changed). |
  110. | `calendar_delete_event` | Delete. |
  111. | `calendar_freebusy` | Query busy windows across multiple calendars — ideal for "find time to meet". |
  112. ### Drive (4)
  113. | Tool | Purpose |
  114. |------|---------|
  115. | `drive_list_files` | List with Drive query syntax filter, pagination, ordering. |
  116. | `drive_search` | Full-text search across file content + names. Optional `mimeType` filter. Excludes trashed. |
  117. | `drive_download_file` | Get file content. Google-native files auto-exported as text; binary returned as base64. |
  118. | `drive_upload_file` | Create file with content + optional `parentFolderId`. Supports utf-8 / base64. |
  119. ### Docs (3)
  120. | Tool | Purpose |
  121. |------|---------|
  122. | `docs_read_doc` | Plain-text extraction from doc body (walks paragraphs + tables). |
  123. | `docs_create_doc` | New doc with title + optional `initialContent`. |
  124. | `docs_update_doc` | `mode: "append"` (at document end) or `mode: "replace"` (wipe body + insert). |
  125. ### Sheets (5)
  126. | Tool | Purpose |
  127. |------|---------|
  128. | `sheets_list_sheets` | Spreadsheet metadata + list of sheet tabs. |
  129. | `sheets_read_range` | Read A1-notation range. Supports `majorDimension` + `valueRenderOption`. |
  130. | `sheets_write_range` | Overwrite values at range. `USER_ENTERED` parses formulas + dates. |
  131. | `sheets_append_row` | Append row(s) to data region end. |
  132. | `sheets_create_spreadsheet` | New spreadsheet with optional initial sheet titles. |
  133. ### Slides (3)
  134. | Tool | Purpose |
  135. |------|---------|
  136. | `slides_read_presentation` | Metadata + plain-text summary per slide. |
  137. | `slides_create_presentation` | New presentation with title. |
  138. | `slides_add_slide` | Insert slide with layout (BLANK / TITLE / TITLE_AND_BODY / SECTION_HEADER / TITLE_AND_TWO_COLUMNS / CAPTION_ONLY). |
  139. **Every tool accepts optional `account` param** (email, case-insensitive). Omit → primary account. Unknown email → `ACCOUNT_NOT_FOUND` error.
  140. **OAuth scopes required** (10 total): `gmail.modify`, `calendar`, `drive.file`, `drive.metadata.readonly`, `documents`, `spreadsheets`, `presentations`, plus OIDC `openid email profile`.
  141. **Google Cloud setup:** Enable 6 APIs in your OAuth project — Gmail, Calendar, Drive, Docs, Sheets, Slides. Missing API returns `PERMISSION_DENIED` with direct enable link.
  142. ---
  143. ## Install
  144. ### Plugin
  145. Requires Obsidian ≥ 0.15 and macOS (Linux + Windows may work; untested).
  146. **Via BRAT (Beta Reviewer plugin, recommended for now):**
  147. 1. Install BRAT from Community Plugins
  148. 2. `Cmd+P` → "BRAT: Add a beta plugin" → `klemensgc/modular-context-obsidian-plugin`
  149. 3. Enable in Settings → Community plugins
  150. **Manual:**
  151. 1. Download `main.js`, `manifest.json`, `styles.css`, `mcp-server.js` from [latest release](https://github.com/klemensgc/modular-context-obsidian-plugin/releases)
  152. 2. Copy to `<vault>/.obsidian/plugins/modular-context/`
  153. 3. Enable plugin in Settings → Community plugins → Modular Context
  154. ### MCP server
  155. **Auto-installed** on first `Google Workspace: Connect`. Plugin copies bundled binary to `~/.modular-context/mcp-google/dist/index.js` (~100 MB one-time).
  156. ---
  157. ## Repo structure
  158. Monorepo with three packages:
  159. ```
  160. modular-context-obsidian-plugin/
  161. ├── packages/
  162. │ ├── plugin/ ← Obsidian plugin (main.ts, manifest, features + MCP client glue)
  163. │ ├── mcp-google/ ← standalone MCP server (25 Google Workspace tools, Node)
  164. │ ├── shared/ ← portable types + AgentTracker + PTY helper + UI primitives
  165. │ └── app/ ← experimental standalone Electron app (WIP, not shipped)
  166. ├── README.md ← you are here
  167. ├── banner.png
  168. └── package.json ← monorepo scripts (build:shared → build:mcp-google → build:plugin)
  169. ```
  170. - **[packages/plugin/CHANGELOG.md](packages/plugin/CHANGELOG.md)** — user-facing release notes (v1.0 → v2.0)
  171. - **[packages/plugin/RELEASE-v2.0.0.md](packages/plugin/RELEASE-v2.0.0.md)** — v2.0 release highlights
  172. - **[packages/mcp-google/README.md](packages/mcp-google/README.md)** — MCP server docs (25 tools, accounts, env contract)
  173. - **[packages/mcp-google/CHANGELOG.md](packages/mcp-google/CHANGELOG.md)** — MCP server version history
  174. - Skill library: separate repo [klemensgc/modular-context-skills](https://github.com/klemensgc/modular-context-skills) — plugin auto-syncs
  175. ---
  176. ## Connect Google Workspace
  177. Two paths:
  178. - **Quick Connect** (no GCP setup) — use the shared OAuth client bundled with the pre-built release. Comment your email on [#3 — Quick Connect: request test-user access](https://github.com/klemensgc/modular-context-obsidian-plugin/issues/3) to be added as a test user (usually within 24h). Then skip to step 5 below.
  179. - **BYO** (your own GCP project) — full control, no test-user limit. Follow all 6 steps below.
  180. ### 6 steps (BYO path)
  181. 1. **Create GCP OAuth Client**
  182. - [Google Cloud Console](https://console.cloud.google.com) → new project (e.g. `modular-context-gcp`)
  183. - Enable APIs: Gmail API, Google Calendar API
  184. - OAuth consent screen → External, Testing mode → add scopes: `gmail.modify`, `calendar`, plus `openid`, `email`, `profile`
  185. - Add yourself as test user
  186. - Create credentials → OAuth 2.0 Client ID → Desktop app
  187. - Copy Client ID + Client Secret
  188. 2. **Fill `.env.local`** in the plugin's build folder:
  189. ```
  190. GOOGLE_OAUTH_CLIENT_ID=...
  191. GOOGLE_OAUTH_CLIENT_SECRET=...
  192. ```
  193. 3. **Rebuild** (`npm run build` in `packages/plugin`) if self-building. Pre-built release uses the shared Quick Connect client.
  194. 4. **Reload plugin** — `Cmd+P` → "Reload app without saving"
  195. 5. **Connect** — `Cmd+P` → "Google Workspace: Connect (or add account)" → browser OAuth → authorize → done
  196. 6. **Add more accounts** — "Google Workspace: Add another account" any time
  197. The plugin writes `.mcp.json` to your vault root + per-account sidecars to `~/.modular-context/mcp-google/accounts/{filename}/`. **Restart Claude Code session** to pick up the MCP server.
  198. ---
  199. ## Plugin commands
  200. | Command | Purpose |
  201. |---------|---------|
  202. | `Google Workspace: Connect (or add account)` | Launch OAuth flow for new/additional account |
  203. | `Google Workspace: Add another account` | Alias for above — clearer intent |
  204. | `Google Workspace: Reconnect (upgrade scopes)` | Nuke tokens, re-auth all accounts with current scope set |
  205. | `Google Workspace: Disconnect all accounts` | Remove all credentials + `.mcp.json` entry |
  206. | `Google Workspace: Status` | List connected accounts, expiry times, scope status |
  207. | `Google Workspace: Show MCP server logs` | Open `~/.modular-context/mcp-google/logs/server.log` |
  208. Plus 5+ non-Google commands for terminal / skill management. See Command Palette.
  209. ---
  210. ## Security
  211. - **Tokens** encrypted via Electron `safeStorage` (OS keychain). Never leave disk in plaintext.
  212. - **Credentials sidecar** for MCP server: plaintext JSON at `0600` perms in user-scope folder (comparable to `~/.aws/credentials`, `~/.config/gcloud/`). Plugin may re-encrypt in v2.1 (see ADR-003 addendum).
  213. - **No telemetry.** No crash reports. No metrics. Zero phone-home.
  214. - **Logs** scrub tokens, emails, subjects via regex on every line.
  215. - **Multi-account isolation.** Each account has separate credentials; MCP server honors `account` param strictly.
  216. Full threat model in [docs/adrs/ADR-003-addendum-shared-state.md](docs/adrs/ADR-003-addendum-shared-state.md).
  217. ---
  218. ## What's new in v2.0
  219. - 3 primary skills reorganization — `Synthesise Files` (was "Ingest Data"), `WhatsApp Digest`, `Gmail + Calendar`
  220. - New `gsuite-analysis` skill — orchestrates 10 MCP tools with 4 playbook patterns
  221. - Graduated v1.5 / v1.6 / v1.7 beta milestones: OAuth + storage + MCP server + multi-account + full control
  222. - OAuth scope upgrade: `gmail.modify` + `calendar` full (replaces `gmail.readonly`, `gmail.send`, `calendar.events`)
  223. - `mcp-google-workspace` @ 1.1.0 stable (from 1.1.0-beta.1)
  224. - New tools: `gmail_send`, `gmail_modify_labels`, `calendar_list_calendars`, `calendar_update_event`, `calendar_delete_event`, `calendar_freebusy`
  225. - **Smart Session Restore Picker** — replaces silent auto-resume on plugin reopen. Modal classifies saved sessions into Needs attention / Idle / Archive buckets; you pick what materializes. No accidental skill re-runs, no hidden respawns.
  226. Full list in [packages/plugin/CHANGELOG.md](packages/plugin/CHANGELOG.md).
  227. ---
  228. ## Troubleshooting
  229. | Issue | Fix |
  230. |-------|-----|
  231. | Notice: "Reconnect required for {email}" | `Google Workspace: Reconnect (upgrade scopes)` — scopes changed |
  232. | `TOKEN_EXPIRED` from MCP tool | User revoked access or refresh token rotated — `Reconnect` |
  233. | `ACCOUNT_NOT_FOUND` | Account not connected — `Add another account` |
  234. | MCP server not visible in Claude Code | Restart Claude Code session. `.mcp.json` loaded at session start. |
  235. | Plugin reloaded but old behavior | Hard reload: `Cmd+P` → "Reload app without saving" (not just disable+enable) |
  236. | Server logs empty | Normal — server only runs when Claude Code calls a tool. Not a daemon. |
  237. ---
  238. ## Contributing
  239. Plugin: [modular-context-obsidian-plugin](https://github.com/klemensgc/modular-context-obsidian-plugin)
  240. Skills library: [modular-context-skills](https://github.com/klemensgc/modular-context-skills) (separate repo, auto-synced)
  241. PRs welcome. Issues welcome. No support contract, but I read everything.
  242. ---
  243. ## License
  244. MIT © klemensgc / receptionOS

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.