GroundEffect

Hyper-fast, local Gmail and Google Calendar indexing for Claude Code.

GroundEffect is a local headless IMAP/CalDav client, Claude Code skill, and MCP server built in Rust with LanceDB.

- Hybrid Search: BM25 full-text + vector semantic search with Reciprocal Rank Fusion
- Local Embeddings: Runs nomic-embed-text-v1.5 locally via Candle with Metal acceleration
- Multi-Account: Connect unlimited Gmail/GCal accounts with independent sync
- MCP Integration: Exposes email and calendar tools directly to Claude Code
- Real-time Sync: IMAP IDLE for instant email notifications, CalDAV polling for calendar
- HTML Text Extraction: Automatically converts HTML emails to clean plain text usinghtml2text
- Pluggable Token Storage: File-based (default) or PostgreSQL with AES-256-GCM encryption

brew tap jamiequint/groundeffect brew install groundeffect

- Installs the daemon (starts at login)
- Installs the Claude Code skill
- Adds permissions to run groundeffect commands

Create a Google Cloud project with OAuth credentials:
- Go toGoogle Cloud Console
- Create a project and enableGmail APIandGoogle Calendar API
- Go toAPIs & Services > Credentials
- CreateOAuth client ID(Desktop app type)
- Add your credentials:

echo 'export GROUNDEFFECT_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"' >> ~/.zshrc echo 'export GROUNDEFFECT_GOOGLE_CLIENT_SECRET="your-client-secret"' >> ~/.zshrc source ~/.zshrc

# Use local embeddings (default) groundeffect config settings --embedding-provider local # Use OpenRouter embeddings export OPENROUTER_API_KEY="your-key" groundeffect config settings --embedding-provider openrouter # Set embedding + IMAP fetch batch size (128 recommended for Gmail/OpenRouter stability) groundeffect config settings --embedding-batch-size 128 # Optional: set a different OpenRouter model groundeffect config settings --openrouter-model "openai/text-embedding-3-large"

{ "mcpServers": { "groundeffect": { "type": "stdio", "command": "groundeffect-mcp", "env": { "GROUNDEFFECT_GOOGLE_CLIENT_ID": "${GROUNDEFFECT_GOOGLE_CLIENT_ID}", "GROUNDEFFECT_GOOGLE_CLIENT_SECRET": "${GROUNDEFFECT_GOOGLE_CLIENT_SECRET}" } } } }

git clone https://github.com/jamiequint/groundeffect.git cd groundeffect cargo build --release

# Install binaries sudo cp target/release/groundeffect* /usr/local/bin/ # Install skill cp -r skill ~/.claude/skills/groundeffect # Install daemon groundeffect daemon install # Add permissions groundeffect config add-permissions

~/.config/groundeffect/ ├── config.toml # Main configuration ├── daemon.toml # Daemon configuration └── tokens/ # OAuth tokens (file provider) ~/.local/share/groundeffect/ ├── lancedb/ # LanceDB database ├── attachments/ # Downloaded attachments ├── models/ # Embedding model files ├── logs/ # Log files └── cache/ └── sync_state/ # Sync state ~/.claude/skills/groundeffect/ # Claude Code skill

cargo build --release --features postgres

CREATE TABLE IF NOT EXISTS groundeffect_tokens ( email VARCHAR(255) PRIMARY KEY, encrypted_tokens BYTEA NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() );

[tokens] provider = "postgres" database_url_env = "DATABASE_URL" encryption_key_env = "GE_TOKEN_ENCRYPTION_KEY" # table_name = "groundeffect_tokens" # optional

export DATABASE_URL="postgres://user:pass@localhost/mydb" export GE_TOKEN_ENCRYPTION_KEY="your-secret-key-here"

Tokens are encrypted at rest using AES-256-GCM with a key derived from your encryption key via HKDF-SHA256.

groundeffect account reauth <email-or-alias>

groundeffect daemon status groundeffect daemon restart

tail -f ~/.local/share/groundeffect/logs/daemon.log

groundeffect config settings --logging true groundeffect daemon restart

Embedding model uses ~500MB-1GB during active embedding. Normal when idle.

┌──────────────┐ ┌──────────────────┐ │ Claude Code │─────►│ groundeffect-mcp │────────┐ │ (MCP Host) │stdio │ │ │ └──────────────┘ └──────────────────┘ │ ▼ ┌──────────────┐ ┌──────────────────┐ ┌─────────┐ │ Claude Code │─────►│ groundeffect │───►│ LanceDB │ │ (Skill/Bash) │ │ (CLI) │ └─────────┘ └──────────────┘ └──────────────────┘ ▲ │ ┌──────────────────┐ │ │ groundeffect- │─────────┘ │ daemon │◄──── IMAP/CalDAV └──────────────────┘

An MCP server for interacting with Gmail and Google Calendar, enabling context-aware email and event management.

Integrate Google services like Gmail, Calendar, Drive, and Tasks with MCP.

(MCP) server for Google Workspace. Drive, Gmail, Calendar, Sheets, Docs, Tasks and People via AI agents.

Interact with Google Workspace services like Gmail and Google Calendar.

Integrates Google Workspace services like Calendar, Drive, and Gmail with AI assistants.

Manage Gmail, Calendar, Drive, and Contacts through Google Workspace APIs using OAuth 2.0.

Interact with Google Workspace services like Gmail and Google Calendar.

An MCP server for interacting with Google Workspace services like Gmail and Calendar.

Interact with Google products, including Gmail and Calendar.

A comprehensive MCP server for managing Google Workspace services like Calendar, Contacts, and Gmail using OAuth2 authentication.