Model Context Protocol (MCP) Server + Google OAuth

This is a Model Context Protocol (MCP) server that supports remote MCP connections, with Google OAuth built-in.

You can deploy it to your own Cloudflare account, and after you create your own Google Cloud OAuth client app, you'll have a fully functional remote MCP server that you can build off. Users will be able to connect to your MCP server by signing in with their Google account.

You can use this as a reference example for how to integrate other OAuth providers with an MCP server deployed to Cloudflare, using the workers-oauth-provider library.

The MCP server (powered by Cloudflare Workers):

• Acts as OAuth Server to your MCP clients

• Acts as OAuth Client to your real OAuth server (in this case, Google)

Credits

This repository was created from the Cloudflare AI remote MCP Google OAuth demo template using:

npm create cloudflare@latest -- cloudflare-mcp-google-auth --template=cloudflare/ai/demos/remote-mcp-google-oauth

All credit goes to the original authors at Cloudflare.

Related MCP server: MCP Access OAuth Server

Getting Started

Clone the repo & install dependencies: npm install

For Production

Create a new Google Cloud OAuth App:

• For the Homepage URL, specify https://mcp-google-oauth.<your-subdomain>.workers.dev

• For the Authorization callback URL, specify https://mcp-google-oauth.<your-subdomain>.workers.dev/callback

• Note your Client ID and generate a Client secret.

Set up a KV namespace and store secrets

This project uses KV service binding instead of environment variables. This approach allows you to store secrets in one place (a KV namespace) and reuse them across multiple MCP workers by binding them to the same KV namespace. This is especially useful when you have multiple MCP servers that need to share the same OAuth credentials.

1. Create a KV namespace with any name (if you don't already have one):

wrangler kv namespace create "MY_KV_STORE"

2. In your Cloudflare Worker settings (dashboard), bind this KV namespace with the binding name OAUTH_KV.

3. Update wrangler.jsonc and replace <Add-KV-ID> with the actual KV namespace ID from step 1

4. Store your OAuth credentials in the KV namespace:

For local development (stores in .wrangler/state/v3/kv):

wrangler kv key put --local "GOOGLE_CLIENT_ID" "<Your Google Client ID>" --binding="OAUTH_KV"
wrangler kv key put --local "GOOGLE_CLIENT_SECRET" "<Your Google Client Secret>" --binding="OAUTH_KV"
wrangler kv key put --local "COOKIE_ENCRYPTION_KEY" "<Random string, e.g. from openssl rand -hex 32>" --binding="OAUTH_KV"
# Optional: use this to restrict Google account domain
# wrangler kv key put --local "HOSTED_DOMAIN" "<your-domain.com>" --binding="OAUTH_KV"

For remote deployment:

wrangler kv key put "GOOGLE_CLIENT_ID" "<Your Google Client ID>" --binding="OAUTH_KV"
wrangler kv key put "GOOGLE_CLIENT_SECRET" "<Your Google Client Secret>" --binding="OAUTH_KV"
wrangler kv key put "COOKIE_ENCRYPTION_KEY" "<Random string, e.g. from openssl rand -hex 32>" --binding="OAUTH_KV"
# Optional: use this to restrict Google account domain
# wrangler kv key put "HOSTED_DOMAIN" "<your-domain.com>" --binding="OAUTH_KV"

Deploy & Test

Deploy the MCP server to make it available on your workers.dev domain:

wrangler deploy

Verify KV Configuration: You can verify that your KV secrets are properly configured by visiting:

https://mcp-google-oauth.<your-subdomain>.workers.dev/test-config

This endpoint will confirm whether your Google OAuth credentials and cookie encryption key are properly stored in KV.

Test the remote server using Inspector:

npx @modelcontextprotocol/inspector@latest

Enter https://mcp-google-oauth.<your-subdomain>.workers.dev/mcp and hit connect. Once you go through the authentication flow, you'll see the Tools working:

You now have a remote MCP server deployed!

Access Control

This MCP server uses Google Cloud OAuth for authentication. All authenticated Google users can access basic tools like "add". To restrict users to a specific hosted domain, store the domain in KV:

# For remote
wrangler kv key put "HOSTED_DOMAIN" "<your-domain.com>" --binding="OAUTH_KV"
# For local
wrangler kv key put --local "HOSTED_DOMAIN" "<your-domain.com>" --binding="OAUTH_KV"

Access the remote MCP server from Claude Desktop

Open Claude Desktop and navigate to Settings -> Developer -> Edit Config. This opens the configuration file that controls which MCP servers Claude can access.

Replace the content with the following configuration. Once you restart Claude Desktop, a browser window will open showing your OAuth login page. Complete the authentication flow to grant Claude access to your MCP server. After you grant access, the tools will become available for you to use.

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-google-oauth.<your-subdomain>.workers.dev/mcp"
      ]
    }
  }
}

Once the Tools (under 🔨) show up in the interface, you can ask Claude to use them. For example: "Could you use the math tool to add 23 and 19?". Claude should invoke the tool and show the result generated by the MCP server.

For Local Development

If you'd like to iterate and test your MCP server, you can do so in local development. This will require you to create another OAuth App on Google Cloud:

• For the Homepage URL, specify http://localhost:8788

• For the Authorization callback URL, specify http://localhost:8788/callback

• Note your Client ID and generate a Client secret.

Store your local development credentials using the commands in step 4 of the Production section above, using the --local flag (see "For local development" subsection).

Develop & Test

Run the server locally to make it available at http://localhost:8788:

wrangler dev

Verify Local KV Configuration: You can verify that your local KV secrets are properly configured by visiting:

http://localhost:8788/test-config

To test the local server, enter http://localhost:8788/mcp into Inspector and hit connect. Once you follow the prompts, you'll be able to "List Tools".

Using Claude and other MCP Clients

When using Claude to connect to your remote MCP server, you may see some error messages. This is because Claude Desktop doesn't yet support remote MCP servers, so it sometimes gets confused. To verify whether the MCP server is connected, hover over the 🔨 icon in the bottom right corner of Claude's interface. You should see your tools available there.

Using Cursor and other MCP Clients

To connect Cursor with your MCP server, choose Type: "Command" and in the Command field, combine the command and args fields into one (e.g. npx mcp-remote https://<your-worker-name>.<your-subdomain>.workers.dev/mcp).

Note that while Cursor supports HTTP+SSE servers, it doesn't support authentication, so you still need to use mcp-remote (and to use a STDIO server, not an HTTP one).

You can connect your MCP server to other MCP clients like Windsurf by opening the client's configuration file, adding the same JSON that was used for the Claude setup, and restarting the MCP client.

How does it work?

OAuth Provider

The OAuth Provider library serves as a complete OAuth 2.1 server implementation for Cloudflare Workers. It handles the complexities of the OAuth flow, including token issuance, validation, and management. In this project, it plays the dual role of:

• Authenticating MCP clients that connect to your server

• Managing the connection to Google Cloud's OAuth services

• Securely storing tokens and authentication state in KV storage

Durable MCP

Durable MCP extends the base MCP functionality with Cloudflare's Durable Objects, providing:

• Persistent state management for your MCP server

• Secure storage of authentication context between requests

• Access to authenticated user information via this.props

• Support for conditional tool availability based on user identity

MCP Remote

The MCP Remote library enables your server to expose tools that can be invoked by MCP clients like the Inspector. It:

• Defines the protocol for communication between clients and your server

• Provides a structured way to define tools

• Handles serialization and deserialization of requests and responses

• Supports both Streamable HTTP (recommended) and Server-Sent Events (SSE) protocols for client communication

Transport Protocol Migration

This example has been updated to support the new Streamable HTTP transport protocol, which replaces the deprecated Server-Sent Events (SSE) protocol. The server now exposes both endpoints:

• /mcp - Recommended: Uses the new Streamable HTTP protocol

• /sse - Deprecated: Legacy SSE protocol (maintained for backward compatibility)

All new integrations should use the /mcp endpoint. The SSE endpoint will be removed in a future version.