Brainforge Knowledge

setup-google-workspace-mcp

5 min read

Setup: Google Workspace MCP (Brainforge)

This guide explains how to install and use the Brainforge Google Workspace MCP from:

  • Cursor (recommended for day-to-day agent workflows)
  • Codex CLI / Codex Desktop

The MCP server is hosted on Railway; you connect to it via URL.

When to use this MCP

For Cursor/agent workflows, use the BrainForge Google Workspace MCP (brainforge-google) as the default path (search/read, structured retrieval, small updates). Fall back to the Google Workspace CLI (gws) for bulk operations, tight iterative loops, or when MCP is unavailable. See google-workspace-cli-setup.md.

How Cursor loads the Google MCP

When you open this repo

The brainforge-platform repo includes a .cursor folder with an mcp.json that points to the Railway-hosted Google Workspace MCP. When you open the brainforge-platform repo as your Cursor workspace (or as a workspace root), Cursor loads that config automatically and the Google MCP is available.

Location: .cursor/mcp.json (at repo root)

{
  "mcpServers": {
    "brainforge-google": {
      "url": "https://google-workspace-mcp-production-bab7.up.railway.app/mcp",
      "headers": {}
    }
  }
}

No extra configuration is needed in that case.

When the playbook is not your top-level workspace

If you open a different folder as your workspace (e.g. the parent BrainforgeAI repo or another project), Cursor looks for MCP config in that workspace’s .cursor/mcp.json or in your user-level settings. The playbook’s .cursor/mcp.json is not used.

In that case, add the Google Workspace MCP entry to your user/workspace MCP config:

  1. Open Cursor Settings → MCP (or edit the config file directly).
  2. Ensure your mcp.json includes the same server entry. For example, merge this into your existing mcpServers:
{
  "mcpServers": {
    "brainforge-google": {
      "url": "https://google-workspace-mcp-production-bab7.up.railway.app/mcp",
      "headers": {}
    }
  }
}
  • User-level config (all projects): ~/.cursor/mcp.json (e.g. C:\Users\<You>\.cursor\mcp.json on Windows, ~/.cursor/mcp.json on macOS/Linux).
  • Workspace-level (current project only): .cursor/mcp.json at the root of the folder you opened in Cursor.

If you use workspace-level, create .cursor/mcp.json in that root with the snippet above (and any other MCPs you want for that workspace).

First-time authentication

Brainforge runs this MCP in OAuth 2.1 mode (protocol-level auth). That means:

  • Each teammate authenticates with their own Google account
  • Your MCP client handles the OAuth flow (you’ll be prompted to open a browser / approve access)
  • The legacy start_google_auth flow may be disabled on the server
  1. Trigger any Google tool call in chat (e.g. “fetch this Google Doc by ID”).
  2. Cursor will prompt you through OAuth. Complete the browser flow.
  3. Retry the original action.

Use the same Google account (e.g. your work email) that has access to the Drive/Docs/Sheets you care about.

Codex CLI

If you’re using Codex CLI, add the server and then run any tool (Codex will drive the OAuth flow):

codex mcp add brainforge-google --url https://google-workspace-mcp-production-bab7.up.railway.app/mcp

Then test with a lightweight call (examples below).

Use an ID you can access:

  • get_doc_content with document_id=<google_doc_id>
  • search_drive_files with a simple query (e.g. by name)

Example Doc ID used during verification:

  • 15Mj4qGQSmxdJv-E4Cg9LMIc02klCaP85NTwH2oPIIT0

Available tools

Once the MCP is loaded and you’re authenticated, these tools are available to Cursor agents. You can use the MCP for email and calendar—no need to search for alternatives; use the tools below.

Gmail

  • search_gmail_messages - Search messages with Gmail query syntax (from/to/subject/query)
  • get_gmail_message_content - Get a single message
  • get_gmail_thread_content - Get full thread (conversation)
  • get_gmail_messages_content_batch / get_gmail_threads_content_batch - Batch fetch
  • draft_gmail_message - Create a draft
  • send_gmail_message - Send an email

Google Calendar

  • list_calendars - List calendars for the authenticated user
  • get_events - Get events (by id or time range; optional keyword query)
  • create_event - Create an event (title, start/end, attendees, optional Meet)
  • modify_event - Update an existing event
  • delete_event - Delete an event
  • query_freebusy - Free/busy for a set of calendars in a time range

For calendar attendees, resolve team member emails from the Supabase team table (Cursor rule: .cursor/rules/supabase-team-user-lookup.mdc); do not hardcode addresses.

Google Drive

  • search_drive_files - Search files with query syntax
  • get_drive_file_content - Read file content
  • create_drive_file - Create new files
  • share_drive_file - Share files with users/groups
  • list_drive_items - List folder contents
  • list_docs_in_folder - List Google Docs in a Drive folder

Google Docs

  • get_doc_content - Extract document text
  • create_doc - Create new documents
  • modify_doc_text - Edit document text
  • find_and_replace_doc - Find and replace text

Google Sheets

  • read_sheet_values - Read cell ranges
  • modify_sheet_values - Write/update cells
  • create_spreadsheet - Create new spreadsheets
  • get_spreadsheet_info - Get spreadsheet metadata

Google Slides

  • create_presentation - Create new presentations
  • get_presentation - Retrieve presentation details
  • batch_update_presentation - Apply updates to slides

MCP not showing or “Disabled”

  • If you didn’t open brainforge-platform as the workspace root, add the brainforge-google entry to your user or workspace mcp.json as in the section above.
  • Reload the window (Command Palette → “Developer: Reload Window”) after changing MCP config.

“Needs authentication” or tools fail

  • Trigger any Google tool in chat; complete the OAuth browser flow; retry.

Permission errors

  • Use a Google account that has access to the Drive/Docs/Sheets you’re trying to use. For shared drives, ensure the account has the right permissions.

Reference

  • BrainForge Google Workspace MCP (Railway): https://google-workspace-mcp-production-bab7.up.railway.app
  • Brainforge-owned MCP/server repo: brainforge-ai/brainforge-mcp_google_workspace
  • Upstream: taylorwilsdon/google_workspace_mcp

This MCP is part of Brainforge’s plugin/MCP infrastructure: the server implementation lives in the Brainforge-owned repo above, while the brainforge-platform monorepo contains the playbooks + MCP client configuration (e.g. .cursor/mcp.json) that point to the hosted service.

Graph View