google_workspace_mcp MCP工具

2. Launch — OAuth 2.1 requires HTTP transport

uvx workspace-mcp --transport streamable-http --tool-tier core uvx workspace-mcp --transport streamable-http --tool-tier extended uvx workspace-mcp --transport streamable-http --tool-tier complete

Prerequisites

Python 3.10+ · uv/uvx · Google Cloud Project with OAuth 2.0 credentials

If you want the GCS credential store backend, install the optional dependency first:

```bash uv sync --extra gcs

Requires Python 3.10+ and uvx

Execute the full test suite (async fixtures require pytest-asyncio)

uv run pytest ```

• uv sync --group test installs only the testing stack if you need a slimmer environment.
• uv run main.py --transport streamable-http launches the server with your checked-out code for manual verification.
• Ruff is part of the dev group because pre-push hooks call ruff check automatically—run it locally before committing to avoid hook failures.

</details>

OAuth 2.1 requires HTTP transport mode

export MCP_ENABLE_OAUTH21=true uv run main.py --transport streamable-http

If `MCP_ENABLE_OAUTH21` is not set to `true`, the server will use legacy authentication, which is suitable for clients that do not support OAuth 2.1.

<details open>
<summary>🔐 <b>How the FastMCP GoogleProvider handles OAuth</b> <sub><sup>← Advanced OAuth 2.1 details</sup></sub></summary>

FastMCP ships a native `GoogleProvider` that we now rely on directly. It solves the two tricky parts of using Google OAuth with MCP clients:

1.  **Dynamic Client Registration**: Google still doesn't support OAuth 2.1 DCR, but the FastMCP provider exposes the full DCR surface and forwards registrations to Google using your fixed credentials. MCP clients register as usual and the provider hands them your Google client ID and, when configured, client secret under the hood.

2.  **CORS & Browser Compatibility**: The provider includes an OAuth proxy that serves all discovery, authorization, and token endpoints with proper CORS headers. We no longer maintain custom `/oauth2/*` routes—the provider handles the upstream exchanges securely and advertises the correct metadata to clients.

The result is a leaner server that still enables any OAuth 2.1 compliant client (including browser-based ones) to authenticate through Google without bespoke code.

**Restricting DCR client redirect URIs:**

By default, any client going through Dynamic Client Registration can declare any `redirect_uri`. For publicly-exposed deployments, this is a phishing vector — an attacker can register a client with a `redirect_uri` they control and harvest authorization codes from tricked users. Set `WORKSPACE_MCP_ALLOWED_CLIENT_REDIRECT_URIS` to a comma-separated allowlist of permitted URIs:

Stateless mode requires OAuth 2.1 to be enabled

export MCP_ENABLE_OAUTH21=true export WORKSPACE_MCP_STATELESS_MODE=true uv run main.py --transport streamable-http ```

Key Features: - No file system writes: Credentials are never written to disk - No debug logs: File-based logging is completely disabled - Memory-only sessions: All tokens stored in memory via OAuth 2.1 session store - Container-ready: Perfect for Docker, Kubernetes, and serverless deployments - Token per request: Each request must include a valid Bearer token

Requirements: - Must be used with MCP_ENABLE_OAUTH21=true - Incompatible with single-user mode - Clients must handle OAuth flow and send valid tokens with each request

This mode is ideal for: - Cloud deployments where persistent storage is unavailable - Multi-tenant environments requiring strict isolation - Containerized applications with read-only filesystems - Serverless functions and ephemeral compute environments

MCP Inspector: No additional configuration needed with desktop OAuth client.

Claude Code: No additional configuration needed with desktop OAuth client.

External OAuth provider mode requires OAuth 2.1 to be enabled

export MCP_ENABLE_OAUTH21=true export EXTERNAL_OAUTH21_PROVIDER=true uv run main.py --transport streamable-http ```

How It Works: - Protocol-level auth enabled: All MCP requests (including initialize and tools/list) require a valid Bearer token, following the standard OAuth 2.1 flow. Unauthenticated requests receive a 401 with resource metadata pointing to Google's authorization server. - External OAuth flow: Your external system handles the OAuth flow and obtains Google access tokens (ya29.*) - Token validation: Server validates bearer tokens by calling Google's userinfo API - Multi-user support: Each request is authenticated independently based on its bearer token - Resource metadata discovery: The server serves /.well-known/oauth-protected-resource (RFC 9728) advertising Google as the authorization server and the required scopes

Key Features: - No local OAuth flow: Server does not provide /authorize, /token, or /register endpoint

Google Custom Search Setup

<details open> <summary>◆ <b>Custom Search Configuration</b> <sub><sup>← Enable web search capabilities</sup></sub></summary>

programmablesearchengine.google.com
/controlpanel/create

→ Configure sites or entire web
→ Note your Engine ID (cx)

developers.google.com
/custom-search/v1/overview

→ Create/select project
→ Enable Custom Search API
→ Create credentials (API Key)

export GOOGLE_PSE_API_KEY=\
  "your-api-key"
export GOOGLE_PSE_ENGINE_ID=\
  "your-engine-id"

   export GOOGLE_PSE_API_KEY="AIzaSy..."
   export GOOGLE_PSE_ENGINE_ID="01764344478..."
   

<sub>View all available tools</sub>

</td>
<td width="50%" align="center">

**◆ Call a Tool**

<sub>Execute a tool with key=value arguments</sub>

</td>
</tr>
</table>

Set URL for remote endpoints with `--url` or the `WORKSPACE_MCP_URL` environment variable.

<details open>
<summary>≡ <b>Advanced: FastMCP CLI</b> <sub><sup>← inspect, install, discover</sup></sub></summary>

The upstream [FastMCP CLI](https://gofastmcp.com/cli) is also bundled and provides additional commands for schema inspection, client installation, and editor discovery. Note that `fastmcp` uses in-memory token storage, so each invocation may re-trigger the OAuth flow.

   export GOOGLE_OAUTH_CLIENT_ID="your-client-id"
   export GOOGLE_OAUTH_CLIENT_SECRET="your-secret"
   

The sidecar is disabled unless `WORKSPACE_MCP_HTTP_PORT` is set. It only exists to bridge local `workspace-cli` calls into a legacy stdio server. Do not use it for normal Claude Code, VS Code, hosted, or multi-user deployments; use streamable HTTP with OAuth 2.1 instead. When enabled, it validates ports in the `1..65535` range, binds to `127.0.0.1`, and logs a warning if the port is already in use while keeping stdio running.

**★ Tool Tiers**

**◆ Docker Deployment**

export GOOGLE_OAUTH_CLIENT_ID=\
  "your-client-id"
export GOOGLE_OAUTH_CLIENT_SECRET=\
  "your-secret"