How-to · 3-minute setup

How to connect Gmail to Claude Desktop with Syncore

By the end of this guide your Claude Desktop session will be able to search, read, send, draft, and triage your Gmail inbox — through the Syncore MCP server, with credentials encrypted on your machine and token refresh handled automatically. No Google Cloud Console, no OAuth client registration, no JSON config file editing.

What you'll need

• A Google account whose Gmail you want the agent to access.
• One of: Claude Desktop, Claude Code, Cursor, Windsurf, Codex CLI, or the ChatGPT desktop app.
• A terminal — macOS Terminal, iTerm, Windows PowerShell, or Linux shell.

Step 1 — Install Syncore

# macOS / Linux
curl -fsSL https://syncorelabs.ai/install.sh | sh

# Windows (PowerShell)
powershell -c "iwr -useb https://syncorelabs.ai/install.ps1 | iex"

The installer downloads the Syncore CLI, daemon, and 74 bundled skills into ~/.syncore/. It also installs the Python uv runtime for skill execution. PATH is updated automatically.

Step 2 — Log in

syncore login

A browser window opens. Sign in with email or Google. On return, the CLI generates a per-device 256-bit master key and stores it in your OS keychain (Keychain Access on macOS, libsecret on Linux, Windows Credential Manager on Windows). All credential files written from this point are AES-256-GCM encrypted with that master key.

Step 3 — Authorise Gmail at /connect

Open syncorelabs.ai/connect in your browser. Find the Gmail tile in the Communication category and click Connect. Google's consent screen asks to grant https://www.googleapis.com/auth/gmail.modify — read, send, and label-modify access — to Syncore Labs. Approve.

The OAuth tokens are encrypted with your master key and written to your end-to-end encrypted Syncore vault. The Syncore daemon on your machine pulls them down and stores a local encrypted copy at ~/.syncore/credentials/gmail.enc.

Step 4 — Configure your AI clients

syncore setup

Output looks like:

✓ Claude Desktop   → ~/Library/Application Support/Claude/claude_desktop_config.json
✓ Claude Code      → ~/.claude/settings.json
✓ Cursor           → ~/.cursor/mcp.json
✓ Windsurf         → ~/.codeium/windsurf/mcp_config.json
✓ Codex CLI        → ~/.codex/config.toml
✓ ChatGPT desktop  → ~/Library/Application Support/OpenAI/ChatGPT/mcp_config.json

Every detected MCP client now points at the Syncore daemon. You don't edit any of these files yourself.

Step 5 — Test it in Claude Desktop

Quit and reopen Claude Desktop (Claude Desktop reads MCP config at startup; a hard restart is required, not just closing the window). In a new conversation, try:

Search my Gmail for emails from my manager this week
and summarise the action items they're asking me to do.

Claude will recognise the gmail__search_emails tool from the Syncore MCP server, call it with a Gmail query like from:[email protected] newer_than:7d, then call read_email on the relevant message ids and synthesise the summary.

Variations: Cursor, Windsurf, Codex, ChatGPT

The setup is identical — syncore setup writes the right config for each. The only client-specific quirks:

• Cursor: fully quit (cmd+Q on macOS, not just close window) before tools appear in Composer.
• Claude Code: picks up new MCP servers on the next session. Run /mcp in a session to confirm.
• Windsurf: Cascade panel auto-discovers tools; restart the IDE if they don't appear.
• Codex CLI: reads ~/.codex/config.toml at start; just run codex again.
• ChatGPT desktop: the MCP integration is currently in beta on Mac; settings → Beta Features must be enabled.

Useful prompts to try

• “Find every invoice email from Stripe this month and total the amounts.”
• “Draft a reply to the latest email from [email protected] — say I'll send the proposal Monday.”
• “Archive every promotional email from last week that I haven't replied to.”
• “Read the email thread with subject ‘Q3 launch plan’ and pull out unresolved questions.”

Troubleshooting

Claude says it can't find any tools.

You probably restarted the wrong Claude. Quit Claude Desktop fully (right-click the dock icon → Quit, or Cmd+Q) and reopen. Run syncore doctor to verify the daemon is running and the config file points at the right binary path.

Tools appear but Gmail returns “authentication failed”.

The OAuth grant lapsed or hasn't synced yet. Run syncore update to re-pull credentials from the vault. If that fails, return to /connect and click Reconnect Gmail.

OAuth scope error: “insufficient scope”.

You granted partial access during the consent screen — Google lets you uncheck individual permissions. Reconnect Gmail at /connect and accept all requested scopes; the skill needs the modify scope to send and label.

Token expired mid-conversation.

The Syncore daemon refreshes Google access tokens every 5 minutes when they're within 10 minutes of expiry. If you see a one-time auth error after the laptop has been asleep, retry the prompt — the next refresh cycle (max 5 minutes) will catch it. The 401 you saw is a one-shot artifact, not a persistent state.

Going further

Gmail is one of 74 Syncore skills. The same 3-minute setup gives your AI agent access to Slack, Notion, GitHub, Google Calendar, Linear, Stripe, Figma, Perplexity, Firecrawl, and more — visit /connect for the full catalog.

Related skills: Gmail · Google Calendar · Google Drive. Or read the same guide for connecting Notion to Cursor.