convez.ai
MCP ServerIntegração & APIsAvançado
klemensgc

Modular Context — Base de Conhecimento Obsidian + Google Workspace para Claude

klemensgc/modular-context-obsidian-plugin

Obsidian + Google Workspace como MCP para Claude Code, estruturado em camadas operacionais

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que expõe seu vault Obsidian como base de conhecimento estruturada (Sources → Wiki → Schema) e integra 25 ferramentas nativas do Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, Slides) para Claude Code. Arquitetura local-first com criptografia via Electron, sem telemetria, ideal para equipes e operações.

Instalação

$npx convez-ai klemensgc/modular-context-obsidian-plugin

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
102
Forks
5
Acompanhando
2
Saúde
28%
Último commit
há 1 mês
Versão
2.4.1
Issues abertas
1
Contribuidores
1

Casos de uso

  • Usar seu vault Obsidian como contexto de IA estruturado para automações em Claude Code
  • Integrar Gmail, Google Calendar e Drive em fluxos de trabalho de IA sem sair do Obsidian
  • Construir stacks de IA para empresas solo (processamento, conhecimento, comunicação, CRM e operações)
  • Sincronizar e auditar bases de conhecimento com reweaving automático via IA

Veredito

Ferramenta sólida para quem trabalha em Obsidian + Google Workspace e quer elevar essas integrações à camada de IA. Arquitetura clara (local-first, criptografada) e bem documentada, mas exige conforto com TypeScript e configuração OAuth. Ideal para builders de automações internas e empresas que operam via IA.

README

A tradução para o português deste README ainda está na fila.

Modular Context | Obsidian LLM Knowledge Base for Strategy, Ops & Comms

banner

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.

Version License Platform Obsidian


What is this?

Two things in one plugin:

  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.

  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.

One install, one onboarding, two productivity frontiers.


🏢 The AI Company Stack

The plugin isn't just a terminal + an MCP server — paired with the skills library 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.

LayerWhat it doesSkills
🎙️ NotetakerTurn raw transcripts, calls and tweets into structured, tagged knowledgeprocess-transcripts, xdaily, graduate
🧠 Self-healing Knowledge BaseThe vault keeps itself current — reweaves stale modules, fixes links, audits structure, syncs sibling vaultsreweave, vault-audit, graph, sync, pulse
📡 Communication layerOne read across mail, WhatsApp and Google Workspace — what's happening and what belongs to youcomms-review, whatsapp-digest, gsuite-analysis
📊 CRM / opsReady skills that connect to ClickUp — review your sales funnel and pull your weekly plan straight from the workspaceclickup-review, review-core, tasklist

Each layer is independently useful; together they run a one-person company on autopilot. Skills install from the in-app library (dependencies auto-resolve).


Architecture

   ┌──────────────────────────────────────────────────────────────────┐
   │  YOUR VAULT — your full context, structured so an LLM works on      │
   │  YOUR reality: projects · people · decisions · history              │
   │                                                                     │
   │  Sources  →  Wiki  →  Schema                                        │
   │  raw input   linked notes   structured & typed (LLM-navigable)      │
   └──────────────────────▲────────────────────────▲───────────────────┘
                    reads  │                        │  writes back
   ╔═══════════════════════╧════════════════════════╧═══════════════════╗
   ║              🦀  CLAUDE CODE  (the operator)  🦀                    ║
   ║                                                                     ║
   ║   ── works on your notes ──        ── works with the world ──       ║
   ║   🦀 Capture     🦀 Keep current    🦀 Communicate  🦀 Operate       ║
   ║   calls & files  fix outdated       read & send      review &       ║
   ║   → notes        notes + links      email·WhatsApp    act (CRM)      ║
   ╚══════════════════════════════════════════╦═════════════════╦═══════╝
                                              ▼                 ▼
   COMMUNICATIONS  (read + send)
   ├─ Gmail       ← search          → send / draft / labels
   └─ WhatsApp    ← read messages     (read-only · macOS)

   OPERATIONS  (read + write)
   └─ ClickUp     ← sales funnel · your tasks · weekly plan  → update · batch actions

   WORKSPACE  (Google · multi-account)
   ├─ Calendar  ← list           → create / update / delete
   ├─ Drive     ← list / search  → download / upload
   ├─ Docs      ← read           → create / update
   ├─ Sheets    ← read           → write / append
   └─ Slides    ← read           → create / add slide

   ── set up by ──▶  Modular Context Plugin  (installs skills · handles Google login)

Architecture decisions (full ADRs in docs/adrs/):

  • ADR-001 — Hybrid OAuth: Quick Connect (shared client) + BYO (user-provided client)
  • ADR-002 — Electron safeStorage token storage (OS keychain)
  • ADR-003 + addendum — MCP server stdio lifecycle + plaintext credentials sidecar
  • ADR-005 — Multi-account storage model (per-account folder + index)

Features

LLM Knowledge Base

  • Multi-terminal split layouts — single, side-by-side, stacked, 2×2, 2×3, 2×4. Up to 8 sessions.
  • Claude Code + Codex — toggle AI provider in settings; auto-launch on new terminal.
  • Skills sidebar — 3 primary skills (full-width), rest in secondary grid. One-click launches.
  • Agent tracker — Working / To Review / Standby states per session.
  • Session glyphs — unique geometric shape per terminal. Skills inherit their icon.
  • Compact mode — 48px icon-only sidebar, maximum terminal real estate.
  • Fullscreen overlay — terminal fills Obsidian; sidebar docks right. Esc to exit.
  • Real PTY — zsh in a pseudo-terminal, not a basic runner.
  • Wiki-link autocomplete — [[ inside terminal searches vault notes.
  • Drag-and-drop — Finder / Obsidian → terminal as shell-escaped paths.
  • Session persistence — tab names, glyphs, layouts survive restarts.
  • 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.
  • Auto-onboarding — first install triggers a setup agent that scaffolds your vault.

G-Suite MCP Server (v2.1 — 25 tools)

  • Multi-account — unlimited Google accounts in parallel (Testing mode: up to 100 test users per account)
  • 25 tools for Claude Code across 6 Workspace products (Gmail ×4, Calendar ×6, Drive ×4, Docs ×3, Sheets ×5, Slides ×3 — see table below)
  • Zero telemetry — no metrics, no crash reports, no external calls beyond OAuth + Google API
  • Local-first — tokens encrypted via OS keychain (macOS Keychain / Windows DPAPI / Linux libsecret via libsecret)
  • Auto-refresh — 50-minute timer per account, 5-minute expiry buffer
  • Error taxonomy — TOKEN_EXPIRED, ACCOUNT_NOT_FOUND, SCOPE_OUTDATED, RATE_LIMITED, PERMISSION_DENIED, QUOTA_EXCEEDED, NETWORK_ERROR
  • Hot reload — server re-reads credentials per tool call, zero-downtime refresh

3 primary skills (post-onboarding)

SkillPurposeUses
Synthesise FilesTurn raw files (transcripts, notes, backlog) into vault modules — categorize, tag, update, reweave neighborsYour vault, optional _transcripts-backlog/
WhatsApp DigestAnalyze WhatsApp groups for action items, blindspots, staleness vs vaultmacOS WhatsApp.app
Gmail + G-SuiteInbox sweep, stale follow-ups, calendar gap analysis, meeting prep, doc extraction, sheet logging, deck prepMCP tools below

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.


25 MCP tools

Gmail (4)

ToolPurpose
gmail_searchQuery with Gmail syntax (is:unread, from:X, after:2026-04-01). Optional body extraction.
gmail_draftCreate draft — not sent. User opens webUrl in Gmail UI to send.
gmail_sendSend immediately. Skip draft for trusted, scripted sends.
gmail_modify_labelsAdd/remove labels — system presets (INBOX, UNREAD, STARRED, IMPORTANT, SPAM, TRASH) + custom labels by name.

Calendar (6)

ToolPurpose
calendar_list_calendarsEnumerate all calendars user has access to.
calendar_list_eventsEvents in time range.
calendar_create_eventCreate event (sendUpdates: "none" default — no auto-invite spam).
calendar_update_eventPatch existing (only provided fields changed).
calendar_delete_eventDelete.
calendar_freebusyQuery busy windows across multiple calendars — ideal for "find time to meet".

Drive (4)

ToolPurpose
drive_list_filesList with Drive query syntax filter, pagination, ordering.
drive_searchFull-text search across file content + names. Optional mimeType filter. Excludes trashed.
drive_download_fileGet file content. Google-native files auto-exported as text; binary returned as base64.
drive_upload_fileCreate file with content + optional parentFolderId. Supports utf-8 / base64.

Docs (3)

ToolPurpose
docs_read_docPlain-text extraction from doc body (walks paragraphs + tables).
docs_create_docNew doc with title + optional initialContent.
docs_update_docmode: "append" (at document end) or mode: "replace" (wipe body + insert).

Sheets (5)

ToolPurpose
sheets_list_sheetsSpreadsheet metadata + list of sheet tabs.
sheets_read_rangeRead A1-notation range. Supports majorDimension + valueRenderOption.
sheets_write_rangeOverwrite values at range. USER_ENTERED parses formulas + dates.
sheets_append_rowAppend row(s) to data region end.
sheets_create_spreadsheetNew spreadsheet with optional initial sheet titles.

Slides (3)

ToolPurpose
slides_read_presentationMetadata + plain-text summary per slide.
slides_create_presentationNew presentation with title.
slides_add_slideInsert slide with layout (BLANK / TITLE / TITLE_AND_BODY / SECTION_HEADER / TITLE_AND_TWO_COLUMNS / CAPTION_ONLY).

Every tool accepts optional account param (email, case-insensitive). Omit → primary account. Unknown email → ACCOUNT_NOT_FOUND error.

OAuth scopes required (10 total): gmail.modify, calendar, drive.file, drive.metadata.readonly, documents, spreadsheets, presentations, plus OIDC openid email profile.

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.


Install

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


Repo structure

Monorepo with three packages:

modular-context-obsidian-plugin/
├── packages/
│   ├── plugin/        ← Obsidian plugin (main.ts, manifest, features + MCP client glue)
│   ├── mcp-google/    ← standalone MCP server (25 Google Workspace tools, Node)
│   ├── shared/        ← portable types + AgentTracker + PTY helper + UI primitives
│   └── app/           ← experimental standalone Electron app (WIP, not shipped)
├── README.md          ← you are here
├── banner.png
└── package.json       ← monorepo scripts (build:shared → build:mcp-google → build:plugin)

Connect Google Workspace

Two paths:

  • 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 to be added as a test user (usually within 24h). Then skip to step 5 below.
  • BYO (your own GCP project) — full control, no test-user limit. Follow all 6 steps below.

6 steps (BYO path)

  1. Create GCP OAuth Client

    • Google Cloud Console → new project (e.g. modular-context-gcp)
    • Enable APIs: Gmail API, Google Calendar API
    • OAuth consent screen → External, Testing mode → add scopes: gmail.modify, calendar, plus openid, email, profile
    • Add yourself as test user
    • Create credentials → OAuth 2.0 Client ID → Desktop app
    • Copy Client ID + Client Secret
  2. Fill .env.local in the plugin's build folder:

    GOOGLE_OAUTH_CLIENT_ID=...
    GOOGLE_OAUTH_CLIENT_SECRET=...
    
  3. Rebuild (npm run build in packages/plugin) if self-building. Pre-built release uses the shared Quick Connect client.

  4. Reload plugin — Cmd+P → "Reload app without saving"

  5. Connect — Cmd+P → "Google Workspace: Connect (or add account)" → browser OAuth → authorize → done

  6. Add more accounts — "Google Workspace: Add another account" any time

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.


Plugin commands

CommandPurpose
Google Workspace: Connect (or add account)Launch OAuth flow for new/additional account
Google Workspace: Add another accountAlias for above — clearer intent
Google Workspace: Reconnect (upgrade scopes)Nuke tokens, re-auth all accounts with current scope set
Google Workspace: Disconnect all accountsRemove all credentials + .mcp.json entry
Google Workspace: StatusList connected accounts, expiry times, scope status
Google Workspace: Show MCP server logsOpen ~/.modular-context/mcp-google/logs/server.log

Plus 5+ non-Google commands for terminal / skill management. See Command Palette.


Security

  • Tokens encrypted via Electron safeStorage (OS keychain). Never leave disk in plaintext.
  • 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).
  • No telemetry. No crash reports. No metrics. Zero phone-home.
  • Logs scrub tokens, emails, subjects via regex on every line.
  • Multi-account isolation. Each account has separate credentials; MCP server honors account param strictly.

Full threat model in docs/adrs/ADR-003-addendum-shared-state.md.


What's new in v2.0

  • 3 primary skills reorganization — Synthesise Files (was "Ingest Data"), WhatsApp Digest, Gmail + Calendar
  • New gsuite-analysis skill — orchestrates 10 MCP tools with 4 playbook patterns
  • Graduated v1.5 / v1.6 / v1.7 beta milestones: OAuth + storage + MCP server + multi-account + full control
  • OAuth scope upgrade: gmail.modify + calendar full (replaces gmail.readonly, gmail.send, calendar.events)
  • mcp-google-workspace @ 1.1.0 stable (from 1.1.0-beta.1)
  • New tools: gmail_send, gmail_modify_labels, calendar_list_calendars, calendar_update_event, calendar_delete_event, calendar_freebusy
  • 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.

Full list in packages/plugin/CHANGELOG.md.


Troubleshooting

IssueFix
Notice: "Reconnect required for {email}"Google Workspace: Reconnect (upgrade scopes) — scopes changed
TOKEN_EXPIRED from MCP toolUser revoked access or refresh token rotated — Reconnect
ACCOUNT_NOT_FOUNDAccount not connected — Add another account
MCP server not visible in Claude CodeRestart Claude Code session. .mcp.json loaded at session start.
Plugin reloaded but old behaviorHard reload: Cmd+P → "Reload app without saving" (not just disable+enable)
Server logs emptyNormal — server only runs when Claude Code calls a tool. Not a daemon.

Contributing

Plugin: modular-context-obsidian-plugin

Skills library: modular-context-skills (separate repo, auto-synced)

PRs welcome. Issues welcome. No support contract, but I read everything.


License

MIT © klemensgc / receptionOS

Ver o original no GitHub

Bom para

Relacionados